On this page
  1. Survey before initialization
  2. Exclude generated and unrelated directories
  3. Configuration reference
  4. Path and schema guarantees
  5. Selecting schema artifacts

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

sh
npx playstack init --survey

Survey 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:

sh
npx playstack init --survey --json

Run interactive initialization when the proposals look right:

sh
npx playstack init

Initialization 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:

sh
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

json
{
  "$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
  }
}
PropertyTypePurpose
$schemastring?Points editors to the JSON Schema shipped with the installed CLI.
databases.<name>.adapterprisma | drizzleSelects the schema representation accepted by this named target.
databases.<name>.dialectpostgresql?Required for Drizzle and omitted for Prisma.
databases.<name>.targetRelative pathDestination for composed database-schema artifacts.
databases.<name>.packagesPackage array or package-to-options mapSelects emitters and optional package variants.
databases.<name>.packages.<package>.artifactsstring[]?Exact synchronized artifact IDs; [] selects none, omission uses non-optional defaults.
databases.<name>.packages.<package>.existingArtifactsstring[]?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.targetsstring[]Selects repository-relative destinations for the Skills corpus.
skills.overridesRecord<skillId, path>?Shadows packaged guidance with a user-owned directory.
updates.gitHostgithubPull-request host used by managed updates.
updates.scheduleCron stringSchedule written by playstack ci init.
updates.requiredCheckstringExisting workflow job required before managed merge.
updates.autoMergebooleanOpt-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:

json
{
  "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 settingSynchronized schemas
OmittedCompatible 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:

json
{
  "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.

Go

Playstack Pro tag
OriginsPricingBlogChangelogStatus

© 2026 Playstack. All rights reserved.

With OSS

By

Commune Software