@sidebase/base-config

@sidebase/base-config

Shared setup for sidebase Nuxt 4 apps. @sidebase/streamctl syncs this package's config files (CI, Dockerfile, tsconfig, lint config, editor settings, ...) into your repo and keeps them up to date. The package also exports ESLint, Prisma and tsconfig helpers.

Quick start

Requires Nuxt 4, Node >= 24.21 and pnpm.

pnpm add -D @sidebase/streamctl
pnpm streamctl init --package @sidebase/base-config

init adds @sidebase/base-config, writes streamctl.config.ts, and runs the first sync. Review the changes and commit them.

Coming from @sidestream-tech/nuxt-config? Follow docs/migration.md instead.

What you get

• owned: streamctl writes the whole file. Local edits show up as drift in check.
• block: only the region between the BEGIN/END streamctl MANAGED BLOCK markers is managed.

sync also updates package.json:

• engines, packageManager, and the version ranges of nuxt, typescript, eslint, oxlint, prisma, @prisma/client, jiti, json-sort-cli and vitest. A range is only raised, never lowered.
• scripts.postinstall (nuxt prepare) and scripts.lint (oxlint, then ESLint).

Everyday use

pnpm streamctl sync      # apply the payload after changing the config
pnpm streamctl check     # CI gate: fails when managed files drifted
pnpm streamctl upgrade   # move to the latest payload version and re-sync

sync stops on conflicts, e.g. a file you edited by hand. Resolve them with pnpm streamctl sync --interactive.

Upgrades

Upgrade by hand with pnpm streamctl upgrade, or let a scheduled workflow open the PRs:

automation: { upgradePr: true },

It runs Mondays at 06:00 UTC. Pick your own time with automation.schedule (a five-field cron) and automation.scheduleTimezone (an IANA name):

automation: { upgradePr: true, schedule: "30 14 * * 5", scheduleTimezone: "Europe/Berlin" },

Day-of-month and day-of-week combine with OR: "0 16 1-7 * 5" is not "first Friday".

The workflow runs streamctl check, lint, typecheck, test and build before it opens the PR. Files that need manual work end up in a draft PR with instructions. When a PR for a newer version opens, older upgrade PRs are closed with a link to it.

By default it uses GITHUB_TOKEN, which may not change .github/workflows/**, so workflow changes are left out of the PR. To include them, set automation.allowWorkflowUpdates: true and add a STREAMCTL_PR_TOKEN secret (a fine-grained PAT or GitHub App token with Contents, Pull requests and Workflows write). That token also makes the PR trigger your normal CI.

Configuration

Everything is configured in streamctl.config.ts. defineNuxtBaseConfig gives you completion and type checking for every option:

import { defineNuxtBaseConfig } from "@sidebase/base-config";

export default defineNuxtBaseConfig({
  package: "@sidebase/base-config",
  base: "nuxt-app",
  version: "0.3.0",
  profile: "nuxt-4",

  ci: { unitTests: true, e2e: true },
  docker: { aptPackages: ["ffmpeg"] },
  automation: { upgradePr: true },
  editor: { i18nSourceLanguage: "en" },
});

Options

Things to know:

• A docker.* text option replaces the default. It does not append, so a buildSteps override must list every build command you still need.
• docker.prismaRuntime and docker.startCommand go together. Without Prisma, set prismaRuntime: "" and a startCommand without migrate deploy, e.g. exec node .output/server/index.mjs. Keep the exec, so node gets SIGTERM.
• Repos with English source strings must set editor.i18nSourceLanguage: "en". Otherwise every sync writes "de" back.
• Adopting pnpm-workspace.yaml replaces your existing file, including any onlyBuiltDependencies. Move those entries to pnpm.onlyBuiltDependencies instead of running pnpm approve-builds, which the next sync reverts.

Customizing managed files

Block files: put your own settings below the END marker. For .editorconfig, later sections win, so an override below the block takes precedence. On the first sync, the block is appended after your existing content, so move that content below the block once.

Opt a file out when the options are not enough:

files: { "Dockerfile": "off" },

streamctl then leaves the file alone, including all future fixes to it.

Keep your own scripts.lint (or any other synced package.json field):

versionSyncExclude: ["scripts.lint"],

Helpers

ESLint

// eslint.config.ts
import { createSidebaseEslint } from "@sidebase/base-config/eslint";

export default createSidebaseEslint({ zod: "full", trpcGuard: true })
  .append({ rules: { "vue/multi-word-component-names": "off" } });

Wraps @antfu/eslint-config, which is a dependency of this package; don't install it yourself. Needs eslint and jiti (for the TypeScript config file) in your devDependencies; sync adds both.

Type-aware linting is off by default; run with LINT_TYPEAWARE=true to enable it.

To silence a single line, use the rule ID:

Prisma

// prisma.config.ts
import "dotenv/config";
import { applyPrismaDevEnv, buildPrismaConfig } from "@sidebase/base-config/prisma";
import { defineConfig } from "prisma/config";

applyPrismaDevEnv(); // optional: localhost defaults for unset DB URLs
export default defineConfig(buildPrismaConfig({ views: true, typedSql: true }));

• buildPrismaConfig reads DATABASE_URL, DIRECT_DATABASE_URL and SHADOW_DATABASE_URL. Migrations use DIRECT_DATABASE_URL, or DATABASE_URL with the pooler parameters removed. views and typedSql enable those Prisma features.
• applyPrismaDevEnv sets localhost defaults for the URLs that are unset, so prisma migrate dev works on a fresh checkout without a .env.

Prisma 6.19 only; prisma and @prisma/client are optional peer dependencies.

tsconfig

The managed tsconfig.json extends @sidebase/base-config/tsconfig.base, the shared strict config, before Nuxt's generated one. You can extend it directly as well.

Troubleshooting

• No version profile could be detected: the repo is not on Nuxt 4. Nuxt 3 is not supported.
• pnpm approve-builds changes disappear: use pnpm.onlyBuiltDependencies.
• .editorconfig settings ignored after the first sync: your old content sits above the managed block. Move it below.
• eslint.config.ts fails to load: add jiti to devDependencies.
• Repo with private npm dependencies: the upgrade workflow installs without registry credentials. Opt it out and use your own.

Developing this package

pnpm lint && pnpm typecheck && pnpm test
pnpm validate:presets   # manifests and cross-file invariants
pnpm e2e:dry-run        # pack, install into a scratch consumer, sync and check
pnpm e2e:docker         # build and start the rendered Dockerfile (needs Docker)

• The payload lives in presets/ (base, and nuxt-app on top of it). The manifests in preset.json define files, options and version baselines.
• Tests check contracts derived from the manifests, so changing a preset file rarely needs a test change.
• Actions in managed workflows are pinned by commit SHA; the tests enforce it.
• Requires streamctl >= 0.4.0 (manifest schema version 4).
• Releases: docs/release.md. Agent conventions: AGENTS.md.