diff --git a/docs/content/docs/cli.mdx b/docs/content/docs/cli.mdx index 8e8e183d..af4287a3 100644 --- a/docs/content/docs/cli.mdx +++ b/docs/content/docs/cli.mdx @@ -13,8 +13,10 @@ BTST has two CLI packages: - `@btst/cli` owns low-level DB schema generation and migrations `@btst/codegen generate` and `@btst/codegen migrate` run the aligned -`@btst/cli@2.2.3` release in isolation. This avoids adding its dependency graph -or competing `btst` binary to the application. +`@btst/cli@2.2.4` release in isolation. This avoids adding its dependency graph +or competing `btst` binary to the application. The delegated CLI still loads +the configuration, environment files, aliases, Better Auth adapter, and ORM +peers from the application directory. ## Init (Codegen) @@ -63,7 +65,7 @@ npx @btst/codegen migrate --config=lib/stack.ts --database-url=postgres://... ``` When a delegated command fails, fix the underlying issue and run the equivalent -`npx @btst/cli@2.2.3 ...` command directly. +`npx @btst/cli@2.2.4 ...` command directly. ## About Better DB @@ -75,7 +77,7 @@ For v3 applications, prefer the codegen passthrough commands above. If a v2 application lists `@btst/cli` in its dependencies, remove it during migration; the pinned one-off CLI keeps Better DB dependencies from polluting the consumer graph. You can still invoke the low-level CLI directly with -`npx @btst/cli@2.2.3`. +`npx @btst/cli@2.2.4`. ## Parameters @@ -93,13 +95,13 @@ Generate database schemas for your ORM from your BTST `dbSchema`: ```bash - npx @btst/cli@2.2.3 generate --config=lib/stack.ts --orm=prisma --output=schema.prisma + npx @btst/cli@2.2.4 generate --config=lib/stack.ts --orm=prisma --output=schema.prisma ``` ```bash - npx @btst/cli@2.2.3 generate --config=lib/stack.ts --orm=drizzle --output=src/db/schema.ts + npx @btst/cli@2.2.4 generate --config=lib/stack.ts --orm=drizzle --output=src/db/schema.ts ``` @@ -109,17 +111,17 @@ Generate database schemas for your ORM from your BTST `dbSchema`: **Using DATABASE_URL environment variable:** ```bash - DATABASE_URL=sqlite:./dev.db npx @btst/cli@2.2.3 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql + DATABASE_URL=sqlite:./dev.db npx @btst/cli@2.2.4 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql ``` **Or using --database-url flag:** ```bash - npx @btst/cli@2.2.3 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql --database-url=sqlite:./dev.db + npx @btst/cli@2.2.4 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql --database-url=sqlite:./dev.db ``` ```bash - npx @btst/cli@2.2.3 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql --database-url=postgres://user:pass@localhost:5432/db + npx @btst/cli@2.2.4 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql --database-url=postgres://user:pass@localhost:5432/db ``` @@ -132,17 +134,17 @@ Migrate your database schema directly (Kysely only). For Prisma and Drizzle, use **Using DATABASE_URL environment variable:** ```bash -DATABASE_URL=sqlite:./dev.db npx @btst/cli@2.2.3 migrate --config=lib/stack.ts +DATABASE_URL=sqlite:./dev.db npx @btst/cli@2.2.4 migrate --config=lib/stack.ts ``` **Or using --database-url flag:** ```bash -npx @btst/cli@2.2.3 migrate --config=lib/stack.ts --database-url=sqlite:./dev.db +npx @btst/cli@2.2.4 migrate --config=lib/stack.ts --database-url=sqlite:./dev.db ``` ```bash -npx @btst/cli@2.2.3 migrate --config=lib/stack.ts --database-url=postgres://user:pass@localhost:5432/db +npx @btst/cli@2.2.4 migrate --config=lib/stack.ts --database-url=postgres://user:pass@localhost:5432/db ``` ### Generate SQL to File @@ -150,23 +152,26 @@ npx @btst/cli@2.2.3 migrate --config=lib/stack.ts --database-url=postgres://user Instead of running migrations directly, generate SQL to a file: ```bash -npx @btst/cli@2.2.3 migrate --config=lib/stack.ts --output=migrations.sql --database-url=sqlite:./dev.db +npx @btst/cli@2.2.4 migrate --config=lib/stack.ts --output=migrations.sql --database-url=sqlite:./dev.db ``` -## Gotchas +## Project config loading -Because the CLI executes your config file to extract the `dbSchema`, there are a few limitations to be aware of: +The CLI executes your config file to extract the `dbSchema`, using the same +project context as the application: -- **Path aliases don't work**: Path aliases (like `@/` or `~/`) configured in your TypeScript config won't work for any imports used in your `stack.ts` file or any files it imports. Use relative paths instead. +- TypeScript path aliases such as `@/` or `~/` are loaded from the project's + `tsconfig.json` or `jsconfig.json`. +- Standard Next.js environment files are loaded in precedence order. Existing + process environment values continue to win. +- A bare `import "server-only"` marker is ignored while evaluating the server + config for schema generation; the remainder of the server import graph still + executes normally. +- Prisma and Drizzle adapter modules, including their ORM peers, resolve from + the application. Keep `better-auth` and the selected ORM installed there. -- **Environment variables**: If your config file or its imports have conditional checks for available environment variables (e.g., checking if `process.env.SOME_VAR` exists), you should also pass those environment variables when running CLI commands: +You can still override a value for one command: ```bash -SOME_VAR=value npx @btst/cli@2.2.3 generate --config=lib/stack.ts --orm=prisma --output=schema.prisma -``` - -or using dotenv-cli: - -```bash -npx dotenv-cli -e .env.local -- npx @btst/cli@2.2.3 generate --orm drizzle --config lib/stack.ts --output db/btst-schema.ts +SOME_VAR=value npx @btst/cli@2.2.4 generate --config=lib/stack.ts --orm=prisma --output=schema.prisma ``` diff --git a/packages/cli/scripts/test-init.sh b/packages/cli/scripts/test-init.sh index 16a3d482..2638fb37 100644 --- a/packages/cli/scripts/test-init.sh +++ b/packages/cli/scripts/test-init.sh @@ -163,10 +163,10 @@ rm .npmrc npm install --save-exact @btst/adapter-memory@2.2.3 next-themes $PLUGIN_EXTRA_PACKAGES $STACK_PEERS success "Installed aligned runtime deps with strict peer resolution" -BTST_CLI_VERSION=$(npx --yes @btst/cli@2.2.3 --version) -test "$BTST_CLI_VERSION" = "2.2.3" +BTST_CLI_VERSION=$(npx --yes @btst/cli@2.2.4 --version) +test "$BTST_CLI_VERSION" = "2.2.4" test ! -e node_modules/@btst/cli -success "Ran @btst/cli@2.2.3 without adding it to the consumer graph" +success "Ran @btst/cli@2.2.4 without adding it to the consumer graph" step "Asserting generated files and patches" test -f "lib/stack.ts" diff --git a/packages/cli/src/utils/__tests__/passthrough.test.ts b/packages/cli/src/utils/__tests__/passthrough.test.ts index 27b65999..f084795c 100644 --- a/packages/cli/src/utils/__tests__/passthrough.test.ts +++ b/packages/cli/src/utils/__tests__/passthrough.test.ts @@ -12,7 +12,7 @@ describe("runCliPassthrough", () => { execa.mockResolvedValue({}); }); - it("runs the aligned Better DB CLI outside the consumer dependency graph", async () => { + it("runs the consumer-aware Better DB CLI from the project cwd", async () => { await expect( runCliPassthrough({ cwd: "/tmp/example", @@ -23,7 +23,7 @@ describe("runCliPassthrough", () => { expect(execa).toHaveBeenCalledWith( "npx", - ["--yes", "@btst/cli@2.2.3", "generate", "--orm=drizzle"], + ["--yes", "@btst/cli@2.2.4", "generate", "--orm=drizzle"], { cwd: "/tmp/example", stdio: "inherit" }, ); }); diff --git a/packages/cli/src/utils/passthrough.ts b/packages/cli/src/utils/passthrough.ts index e3e4da83..e0e91437 100644 --- a/packages/cli/src/utils/passthrough.ts +++ b/packages/cli/src/utils/passthrough.ts @@ -2,7 +2,7 @@ import { execa } from "execa"; import { ADAPTERS } from "./constants"; import type { Adapter } from "../types"; -const BETTER_DB_CLI_SPEC = "@btst/cli@2.2.3"; +const BETTER_DB_CLI_SPEC = "@btst/cli@2.2.4"; export function adapterNeedsGenerate(adapter: Adapter): boolean { if (adapter === "memory") return false;