Configuration
Configure Playstack artifact targets, lint adoption, Skills installation, and managed updates in one committed file.
The CLI reads playstack.json from the repository root. Commit this file so local work, CI checks, and managed update branches use the same package selections and ownership boundaries.
Survey before initialization
npx playstack init --surveySurvey mode recognizes root and nested Nx projects, Next Pages and App Router applications, Nest APIs and workers, Redis and BullMQ usage, datasource-bearing Prisma contexts, generated schema derivatives, package-manager state, installed Playstack packages, and likely artifact destinations. It reports proposals without writing files or installing dependencies.
Use --json for one machine-readable object with no human prelude:
npx playstack init --survey --jsonRun interactive initialization when the proposals look right:
npx playstack initInitialization confirms every target before writing. Optional package scripts, a doctor --check CI step, and configured Skills installation are each proposed and confirmed independently.
Exclude generated and unrelated directories
Survey discovery skips generated .app, .app.dSYM, and .xcarchive bundles, Rust target directories, .contentlayer, .expo, and .turbo output by default. Add repeatable repository-relative directory exclusions when needed:
npx playstack init --survey --json --exclude='.prismark/**' --exclude='scratch'Patterns use / separators and apply to project-root and technology discovery. They cannot re-include generated output or bypass symlink exclusions. Inspect the survey before accepting proposals; discovery is not runtime qualification.
Utility packages do not require a capability recipe. For example, inspect playstack info @playstack/crypto, install the package and its dependencies with your existing package manager, and use its supported /primitives entry point directly. The CLI does not replace dependency ownership or application composition.
Configuration reference
{
"$schema": "./node_modules/@playstack/cli/playstack.schema.json",
"databases": {
"primary": {
"adapter": "prisma",
"target": "prisma/schema",
"packages": {
"@playstack/accounts": {},
"@playstack/events-prisma": {}
}
}
},
"emails": { "target": "src/emails/playstack" },
"content": { "target": "content/playstack" },
"i18n": { "target": "src/i18n/playstack" },
"lint": {
"target": "eslint.playstack.config.mjs",
"recommended": true,
"chakra": {
"files": ["src/**/*.{ts,tsx}"],
"tokens": ["fg.default", "bg.canvas", "border.default"]
}
},
"skills": {
"targets": [".agents/skills"],
"overrides": {
"event-design": ".playstack-overrides/event-design"
}
},
"updates": {
"gitHost": "github",
"schedule": "0 9 * * 1",
"requiredCheck": "test",
"autoMerge": false
}
}| Property | Type | Purpose |
|---|---|---|
$schema | string? | Points editors to the JSON Schema shipped with the installed CLI. |
databases.<name>.adapter | prisma | drizzle | Selects the schema representation accepted by this named target. |
databases.<name>.dialect | postgresql? | Required for Drizzle and omitted for Prisma. |
databases.<name>.target | Relative path | Destination for composed database-schema artifacts. |
databases.<name>.packages | Package array or package-to-options map | Selects emitters and optional package variants. |
databases.<name>.packages.<package>.artifacts | string[]? | Exact synchronized artifact IDs; [] selects none, omission uses non-optional defaults. |
databases.<name>.packages.<package>.existingArtifacts | string[]? | Declares artifacts that the existing schema must fully satisfy before they can be skipped. |
emails, content, i18n | { target, packages? } | Selects an artifact kind, destination, and optional emitter allowlist. |
lint | { target, recommended?, extension?, chakra? } | Configures the managed flat ESLint fragment and scoped presets. |
skills.targets | string[] | Selects repository-relative destinations for the Skills corpus. |
skills.overrides | Record<skillId, path>? | Shadows packaged guidance with a user-owned directory. |
updates.gitHost | github | Pull-request host used by managed updates. |
updates.schedule | Cron string | Schedule written by playstack ci init. |
updates.requiredCheck | string | Existing workflow job required before managed merge. |
updates.autoMerge | boolean | Opt-in policy for eligible managed updates. |
Path and schema guarantees
Every target and override must be a relative path confined to the repository. Absolute paths and parent traversal fail before the CLI writes anything.
For Prisma, target must be the complete datasource-bearing schema folder; the
example assumes its datasource is in prisma/schema. Setting a target never
creates a database or applies migrations. Select scope only when the installed
package manifest declares that variant: Accounts has no account variant.
Email/content/i18n target paths do not make a package an emitter. Only explicitly
allowlist packages that publish that artifact kind; Auth does not publish email
templates. The target-only entries above discover compatible installed emitters
and do not configure transactional delivery or author application templates.
Invalid types and malformed values fail configuration loading. Unknown keys warn during the preview period so a typo is visible without blocking forward-compatible experimentation; the published schema supplies editor completion and validation.
Artifact commands can establish one missing target interactively. See Artifact synchronization for that focused workflow.
If exactly one database is configured, database sync selects it automatically. With several databases, interactive use prompts for a target and automation must provide --database=<name>.
Database package options can select individual artifacts or ask Playstack to verify that application-owned storage already satisfies them:
{
"databases": {
"primary": {
"adapter": "prisma",
"target": "prisma/schema",
"packages": {
"@playstack/accounts": {
"existingArtifacts": ["accounts.prisma"]
},
"@playstack/auth": {
"artifacts": ["auth.prisma"]
}
}
}
}
}Unknown, incompatible, duplicate, or overlapping artifact IDs fail before mutation. existingArtifacts is fail-closed: a package artifact is skipped only after the existing schema satisfies its physical storage contract.
Selecting schema artifacts
Selection applies after the database format and any declared variant:
artifacts setting | Synchronized schemas |
|---|---|
| Omitted | Compatible non-optional defaults, except IDs selected as existing. |
[] | None; existingArtifacts are still validated independently. |
["<manifest-id>"] | Exactly those compatible IDs; include every schema your configured native adapters require. |
Schemas marked optional: true are never selected implicitly. Name them in
artifacts to synchronize them, or in existingArtifacts to verify an existing
application schema. Notifications' inbox, queue and admission schemas are all
independently optional. For a queue-only host that already owns compatible native
queue tables, use:
{
"databases": {
"primary": {
"adapter": "prisma",
"target": "prisma/schema",
"packages": {
"@playstack/notifications": {
"artifacts": [],
"existingArtifacts": ["notifications.queue.prisma"]
}
}
}
}
}doctor --check validates that existing queue contract without proposing an inbox
or admission schema. For a new managed queue schema, use
artifacts: ["notifications.queue.prisma"] and omit existingArtifacts.
An inApp notification definition still requires an inbox adapter and compatible
schema; selection does not disable runtime requirements. These rules require the
updated CLI and Notifications artifacts, not merely an unchanged prerelease label.
Selecting fewer schemas neither deletes old managed files nor qualifies the live
database. Application-owned persistence uses the explicit unmanagedPackages
boundary; it is not proof of native-schema satisfaction.
Use named databases with an explicit adapter. A top-level prisma object is unsupported and rejected before artifact writes.