Local development workflow

Development workflows for Rust crates and TypeScript packages

Rust crates

When working on Rust crates in the crates/ directory, follow this workflow:

After each change

Format your code using cargo fmt:

cargo fmt

When a change is ready

1. Lint the code

   Run the Rust linter:

   cargo clippy
   
2. Build the package

   Build a specific package:

   cargo build -p <package>
   
3. Run tests

   Test a specific package:

   cargo test -p <package>
   

   To run a specific test or test group:

   cargo test -p <package> "test_name"
   

Formatting configuration

The project uses rustfmt with custom configuration in rustfmt.toml. Key settings include:

• Field init shorthand
• Try shorthand
• Nightly features enabled
• Vertical imports layout
• Comment wrapping

TypeScript monorepo

When working on TypeScript packages in the npm-packages/ directory, follow this workflow:

After each modification

Format your code using dprint:

npx dprint fmt

The project uses dprint with prettier plugin for consistent formatting.

When the change is ready

1. Lint the code

   Run the JavaScript linter:

   npm run lint
   
2. Build the package

   Build a specific package and its dependencies:

   just rush build -t <package>
   
3. Run tests

   To run a specific test file, navigate to the package directory:

   cd npm-packages/<package>/
   npm run test -- <file>
   

Dependencies management

This project uses Rush to manage dependencies.

After modifying the dependencies of a package, run:

just rush update

Common Rush commands:

• just rush build - Build all projects in npm-packages
• just rush rebuild - Build when Rush doesn’t realize something’s changed
• just rush install - Install dependencies when the repo has changed JS deps
• just rush update - Update dependencies when you’re changing JS deps

Code organization

The Convex Backend project is organized into several key areas:

Client libraries

The JavaScript/React libraries for Convex:

npm-packages/convex/src/

CLI

The command-line tool for Convex users (npx convex):

npm-packages/convex/src/cli/

Dashboard

The web user interface for Convex users:

• npm-packages/dashboard/ - Convex Cloud dashboard (https://dashboard.convex.dev/)
• npm-packages/dashboard-self-hosted/ - Self-hosted build of the dashboard
• npm-packages/dashboard-common/ - Code common to both dashboard versions
• npm-packages/@convex-dev/design-system/ - UI elements
• npm-packages/system-udfs/ - Convex functions the dashboard/CLI can call on deployments

Documentation

Public docs at https://docs.convex.dev/:

npm-packages/docs/

Local backend management

Running the local backend

Start the open source Convex backend on port 3210:

just run-local-backend

Running the dashboard

Run the self-hosted dashboard locally:

just run-dashboard

Resetting local data

Clear any data or stored files from the local backend:

just reset-local-backend

This command removes:

• convex_local_storage/ directory
• convex_local_backend.sqlite3 file

Using Just commands

The project uses Just as a command runner instead of Makefiles. Just avoids several footguns associated with Makefiles.

To see all available commands:

just --list

Or simply:

just