Engineering

Live from docs

Welcome

Welcome to the Engineering Team! We're glad you're here. Before you dive in, please take a moment to set up your core tools.

1. Get the Tools

We recommend using Cursor or Antigravity for the best development experience.

2. Set Up Accounts

Make sure to set up your account with your work email to access all internal resources.

3. Check the Repo

Familiarize yourself with our GitHub Repository.

Getting Started

Open a terminal and paste each command below. If the tool is already installed, great! If not, it will install.

1. Install Node.js

What is this? Node.js is the engine that runs our JavaScript code on your computer (the server), just like your browser runs it on the web.

We recommend Node.js v18 or higher.

brew install node or download from nodejs.org

2. Install Yarn

What is this? Yarn is a "package manager". It acts like an app store for code libraries, downloading all the tools we need so we don't have to write everything from scratch.

npm install -g yarn

3. Clone & Install Dependencies

What is this? "Cloning" downloads the entire codebase from the cloud (GitHub) to your machine. "Installing dependencies" reads our recipe list (package.json) and downloads the ingredients (libraries) using Yarn.

git clone https://github.com/ACME-STEAM-Co/monorepo.git cd monorepo yarn install

4. Set Up Environment (Secure)

What is this? "Environment Variables" are secret settings (like passwords and API keys) that we keep strictly separate from the code to prevent hacking.

🛑 Security Checkpoint

We never put real secrets in the codebase.

1. Copy the example file to create your local config:
cp .env.example .env

2. Call the Engineering Lead (or ask securely in person) to get the actual secrets. Do not email or Slack them.

Safety & Flywheels

How we keep the project fast, tidy, and safe while we experiment.

The Dev Flywheel

Science requires experimentation, but software requires stability. We use a concept called a "Flywheel"—a checklist of safe habits that keeps our momentum going without breaking things.

  • Check your branch: Always work on a new branch, never `main`.
  • Test often: Run `yarn test` to make sure your changes didn't break existing experiments.
  • Commit small: Save your work in small chunks so it's easier to undo if needed.

See DEV_FLYWHEEL.md for the full checklist.

Coding with AI Agents

You don't have to code alone! We encourage using AI agents like Antigravity and Cursor.

Think of them as a "pair programmer" sitting next to you. You can ask them to explain code, write test scripts, or even refactor whole files.

Tip: Ask the agent "Explain this file to me like I'm a scientist" to get a high-level overview.

Running the Apps

Start all applications with a single command:

yarn start:all

This starts:

Individual Apps

yarn start:fe # Frontend only (web app) yarn start:desktop # Desktop app only yarn start:website # Marketing website

Validation & CI

Run these before committing:

yarn ci:local # Run local CI replication yarn typecheck:all # Type check all apps yarn validate:all # Run full validation

Quick Checks

yarn test # Run tests yarn lint # Check linting yarn build # Build for production

Common Gotchas

Things that might trip you up:

Server files don't hot-reload

Changes to +page.server.ts require a restart. Stop and re-run yarn start:all.

process.cwd() is app-specific

In SvelteKit, process.cwd() returns the app directory, not the monorepo root. Use the root detection pattern from MONOREPO.md.

Vite may cache barrel exports

If imports seem stale, try direct imports: import X from '@steamco/pkg/src/...'

Auth checks in two places

Authentication can redirect from both hooks.server.ts and +page.server.ts load functions. Check both when debugging auth issues.