Skip to main content

Development Guide

This guide covers common development tasks and commands for working with the Substrate monorepo.

Common Commands​

Building​

Build all projects:

nx run-many -t build

Build a specific project:

nx run web:build
nx run shared-components:build

Testing​

Run all tests:

nx run-many -t test

Run tests for a specific project:

nx run shared-components:test

Linting​

Lint all projects:

nx run-many -t lint

Lint a specific project:

nx run web:lint

Cleaning Build Artifacts​

Substrate generates various build artifacts, caches, and temporary files during development and builds. These can accumulate over time and take up disk space. The clean task helps manage these artifacts.

Clean a Specific Project​

Each project has a clean task that removes its build artifacts:

# Clean a Next.js application
nx run web:clean

# Clean a package
nx run shared-components:clean

This removes:

  • Build outputs (dist/, .next/)
  • Compilation caches (.swc/, .tsbuildinfo)
  • Generated code (src/generated/, docs/api/)
  • Storybook builds

Clean All Projects​

To clean build artifacts from all projects at once:

nx run-many -t clean

Global Clean​

For a complete cleanup including workspace-level caches and build outputs:

# Clean all projects + workspace dist and Nx cache
yarn clean

# Clean all projects + workspace dist, Nx cache, and node_modules cache
yarn clean:all

The yarn clean command:

  1. Runs the clean task for all projects
  2. Removes the workspace dist/ directory
  3. Removes the .nx/cache directory

The yarn clean:all command additionally removes node_modules/.cache.

What Gets Cleaned​

Different project types clean different artifacts:

Next.js Applications (apps/web, apps/placeholder):

  • .next/ - Next.js build output
  • .swc/ - SWC compilation cache
  • dist/ - Distribution directory (if present)

Documentation App (apps/docs):

  • static/storybook/ - Embedded Storybook build
  • dist/docs - Docusaurus build output

TypeScript Packages (packages/shared-*):

  • dist/ - Compiled TypeScript output
  • docs/api/ - Generated API documentation (TypeDoc)

Packages with Code Generation:

  • shared-db: src/generated/ - Generated Prisma client code
  • shared-graphql: src/generated/ - Generated GraphQL types

Packages with Storybook:

  • dist/storybook/{package-name} - Storybook static build

When to Clean​

You should run a clean when:

  • Build artifacts are causing issues or seem corrupted
  • You want to free up disk space
  • You're troubleshooting caching issues
  • You want to ensure a completely fresh build
  • After pulling major changes from the repository

Clean vs. Cache​

Note that cleaning is different from Nx's cache management:

  • yarn clean - Removes build artifacts and Nx cache
  • Nx cache is automatically managed and cleaned by Nx based on your settings
  • The .nx/cache directory can safely be deleted; Nx will recreate it as needed

Development Workflow​

A typical development workflow might look like:

# Start fresh with a clean workspace
yarn clean

# Build all dependencies
nx run-many -t build

# Start development server for your app
nx run web:dev

# Run tests in watch mode (in another terminal)
nx run web:test --watch

# Lint before committing
nx run web:lint

Using Nx Effectively​

Run Multiple Tasks​

# Run build, test, and lint for a project
nx run-many -t build,test,lint -p web

# Run the same tasks for all projects
nx run-many -t build,test,lint

Understanding Task Dependencies​

Nx automatically handles task dependencies. For example:

  • build depends on ^build (builds dependencies first)
  • test depends on ^build (builds dependencies before testing)

Affected Commands​

Work only with projects affected by your changes:

# Build only affected projects
nx affected -t build

# Test only affected projects
nx affected -t test

Troubleshooting​

"Module not found" errors​

Try cleaning and rebuilding:

yarn clean
nx run-many -t build

Stale cache issues​

Clear the Nx cache:

rm -rf .nx/cache

Or use the global clean:

yarn clean

TypeScript errors after pulling changes​

Rebuild all projects:

nx run-many -t build