Setting up a development environment#

This page describes how to set up a development environment for the Squareone monorepo.

To get the Squareone codebase, fork the Squareone repository if you’re an external contributor, or clone it if you’re a member of the repository or SQuaRE:

git clone https://github.com/lsst-sqre/squareone

Node.js#

Squareone uses Node.js. To get a version of Node.js that matches how we run Squareone in CI and production, use nvm. First, follow the nvm installation documentation then activate the node environment in a cloned Squareone repository:

nvm use

Tip

The node version is defined by the .nvmrc file in the Squareone repository.

pnpm#

Squareone uses pnpm to manage Node.js dependencies. See the pnpm installation documentation to install it.

Install Squareone dependencies#

Install the JavaScript packages:

pnpm install turbo --global
pnpm install

When you install the Squareone monorepo package, it will also install the Husky-based pre-commit hooks that lint the codebase.

Installing turbo globally is recommended so that you have the turbo command available. This globally-installed turbo will defer to the turbo installed in the Squareone monorepo, so don’t worry about minor version mismatches.

Turborepo remote caching#

The Squareone monorepo supports optional remote caching for faster builds using a custom Turborepo cache server at https://roundtable.lsst.cloud/turborepo-cache.

External contributors: no setup required. Run commands normally (pnpm build, pnpm dev, etc.). You’ll still use Turborepo’s local caching, provides significant speedups for repeated tests and builds. The remote cache is optional and does not affect your ability to contribute.

Rubin Observatory staff: If you want to use the remote cache, you’ll need to authenticate. The TURBO_TOKEN is a Gafaelfawr user access token for roundtable.lsst.cloud with the write:git-lfs scope.

Note

If TURBO_API, TURBO_TOKEN, and TURBO_TEAM are already set as environment variables (e.g., in CI/CD pipelines with secret injection), the wrapper will automatically use them without requiring any configuration files.

Choose one of the following authentication methods:

1Password authentication

Use 1Password CLI for secure credential management (recommended for personal machines).

Install 1Password CLI (if not already installed):
```
brew install 1password-cli
```
Sign in to 1Password CLI:
```
op signin lsstit.1password.com
```
This ensures you’re signed into the LSST IT account where the Employee vault is located.
Store credentials in 1Password:

Create an item in your “Employee” vault (lsstit.1password.com account) named “Turborepo Remote Cache” with these fields:
- api-url: https://roundtable.lsst.cloud/turborepo-cache
- team: lsst-sqre
- token: Your Gafaelfawr user access token (obtain from roundtable.lsst.cloud)
Create .env.op file in the repository root:
```
cp .env.op.example .env.op
```
The file should contain:
```
TURBO_API="op://Employee/Turborepo Remote Cache/api-url"
TURBO_TOKEN="op://Employee/Turborepo Remote Cache/token"
TURBO_TEAM="op://Employee/Turborepo Remote Cache/team"
```
The wrapper automatically uses the lsstit.1password.com account. Adjust the vault name (“Employee”) and item name if you stored the credentials differently.
Run commands normally - authentication happens automatically:
```
pnpm build  # Uses remote cache via 1Password
```

The wrapper script will detect .env.op and automatically use op run to inject your credentials securely.

.env file authentication

Use a plain .env file for direct environment variable access.

Create .env file in the repository root:
```
cp .env.example .env
```

Fill in your credentials in .env:

TURBO_API=https://roundtable.lsst.cloud/turborepo-cache
TURBO_TOKEN=your-gafaelfawr-token-here
TURBO_TEAM=lsst-sqre

Run commands normally:

pnpm build  # Uses remote cache via .env

The wrapper script will detect .env and automatically load these variables using dotenv. This file should never be committed to Git and is included in .gitignore.

See Turborepo remote caching for more details about the remote cache authentication system, troubleshooting, and infrastructure information.

Python dependencies for documentation with uv#

The Squareone documentation uses Sphinx, a Python-based documentation generator. To make it easier to install and manage Python dependencies, we use uv to manage a virtual environment and run tasks in them. See the uv installation documentation for details.

Next steps#

See Development tasks for common development tasks.