diff --git a/README.md b/README.md index af294cf74..8bd6e0e70 100644 --- a/README.md +++ b/README.md @@ -123,7 +123,7 @@ This is for you if you want to contribute to the Stack Auth project or run the S ### Setup -Pre-populated .env files for the setup below are available and used by default in `.env.development` in each of the packages. (Note: If you're creating a production build (eg. with `pnpm run build`), you must supply the environment variables manually.) +Note: 24GB+ of RAM is recommended for a smooth development experience. In a new terminal: @@ -154,15 +154,53 @@ You can now open the dev launchpad at [http://localhost:8100](http://localhost:8 Your IDE may show an error on all `@stackframe/XYZ` imports. To fix this, simply restart the TypeScript language server; for example, in VSCode you can open the command palette (Ctrl+Shift+P) and run `Developer: Reload Window` or `TypeScript: Restart TS server`. +Pre-populated .env files for the setup below are available and used by default in `.env.development` in each of the packages. However, if you're creating a production build (eg. with `pnpm run build`), you must supply the environment variables manually (see below). -### Database migrations - -If you make changes to the Prisma schema, you need to run the following command to create a migration file: +### Useful commands ```sh -pnpm run db:migration-gen +# NOTE: +# Please see the dev launchpad (default: http://localhost:8100) for a list of all running services. + +# Installation commands +pnpm install: Installs dependencies + +# Types & linting commands +pnpm typecheck: Runs the TypeScript type checker. May require a build or dev server to run first. +pnpm lint: Runs the ESLint linter. Optionally, pass `--fix` to fix some of the linting errors. May require a build or dev server to run first. + +# Build commands +pnpm build: Builds all projects, including apps, packages, examples, and docs. Also runs code-generation tasks. Before you can run this, you will have to copy all `.env.development` files in the folders to `.env.production.local` or set the environment variables manually. +pnpm build:packages: Builds all the npm packages. +pnpm codegen: Runs all the code-generation tasks, eg. Prisma client and OpenAPI docs generation. + +# Development commands +pnpm dev: Runs the development servers of the main projects, excluding most examples. On the first run, requires the packages to be built and codegen to be run. After that, it will watch for file changes (including those in code-generation files). If you have to restart the development server for anything, that is a bug that you can report. +pnpm dev:full: Runs the development servers for all projects, including examples. +pnpm dev:basic: Runs the development servers only for the necessary services (backend and dashboard). Not recommended for most users, upgrade your machine instead. + +# Environment commands +pnpm start-deps: Starts the Docker dependencies (DB, Inbucket, etc.) as Docker containers, and initializes them with the seed script & migrations. Note: The started dependencies will be visible on the dev launchpad (port 8100 by default). +pnpm stop-deps: Stops the Docker dependencies (DB, Inbucket, etc.) and deletes the data on them. +pnpm restart-deps: Stops and starts the dependencies. + +# Database commands +pnpm db:migration-gen: Currently not used. Please generate Prisma migrations manually (or with AI). +pnpm db:reset: Resets the database to the initial state. Run automatically by `pnpm start-deps`. +pnpm db:init: Initializes the database with the seed script & migrations. Run automatically by `pnpm db:reset`. +pnpm db:seed: Re-seeds the database with the seed script. Run automatically by `pnpm db:init`. +pnpm db:migrate: Runs the migrations. Run automatically by `pnpm db:init`. + +# Testing commands +pnpm test : Runs the tests. Pass `--bail 1` to make the test only run until the first failure. Pass `--no-watch` to run the tests once instead of in watch mode. + +# Various commands +pnpm explain-query: Paste a SQL query to get an explanation of the query plan, helping you debug performance issues. +pnpm verify-data-integrity: Verify the integrity of the data in the database by running a bunch of integrity checks. This should never fail at any point in time (unless you messed with the DB manually). ``` +Note: When working with AI, you should keep a terminal tab with the dev server open so the AI can run queries against it. + ### Chat with the codebase Storia trained an [AI on our codebase](https://sage.storia.ai/stack-auth) that can answer questions about using and contributing to Stack Auth. diff --git a/package.json b/package.json index b02fbda77..f3c162b0f 100644 --- a/package.json +++ b/package.json @@ -16,9 +16,6 @@ "build:demo": "pnpm pre && turbo run build --filter=demo-app...", "build:docs": "pnpm run build:packages && pnpm run build:backend && turbo run generate-openapi-fumadocs && pnpm run --filter=@stackframe/stack-docs generate-openapi-docs && turbo run build --filter=@stackframe/stack-docs", "build:packages": "pnpm pre && turbo run build --filter=./packages/*", - "claude-code": "pnpm pre && pnpx @anthropic-ai/claude-code@latest", - "cmux": "pnpm pre && pnpx cmux@latest", - "codebuff": "pnpm pre && pnpx codebuff", "restart-dev-in-background": "pnpm pre && pnpm run kill-dev:named && (pnpm run dev:named > dev-server.log.untracked.txt 2>&1 &) && echo 'Starting dev server in background... (Logs are in dev-server.log.untracked.txt)' && pnpx wait-on http://localhost:${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}02 -t 120000 && echo 'Dev server running.'", "restart-dev-environment": "pnpm pre && concurrently \"pnpm run build:packages && pnpm run codegen\" \"pnpm run restart-deps\" && pnpm run restart-dev-in-background", "stop-dev-environment": "pnpm pre && pnpm run kill-dev:named && pnpm run stop-deps",