Artifact synchronization
Preview, write, and verify package-owned database-schema, email, content, and translation artifacts.
Playstack packages can publish application-facing files without hiding them behind runtime generation. The CLI verifies those files, resolves their configured destinations, and writes reviewable output into the application repository.
Supported artifact kinds
| Kind | Command | Typical output |
|---|---|---|
database-schema | playstack database sync | Prisma or Drizzle schema artifacts selected by named target, package, and variant. |
emails | playstack emails init | Package-owned transactional email templates. |
content | playstack content init | Content files intended to be adapted by the application. |
i18n | playstack i18n init | Translation resources owned by an installed package. |
source | playstack eject | Explicitly ejectable source artifacts, not ordinary managed sync output. |
Preview before writing
npx playstack database sync --dry-run
npx playstack database compatibility --database=primary
npx playstack database sync --database=primary --diff
npx playstack database sync --check
npx playstack doctor --check--dry-run reports planned changes without writing. --diff adds the generated difference and implies a dry run. --check is intended for CI: it exits non-zero when managed output is stale and never prompts or writes.
Email, content, and translation commands use the same write flags:
npx playstack emails init --diff
npx playstack content init --check
npx playstack i18n initResolve package artifacts
An emitting package publishes playstack.artifacts.json. Each entry declares:
| Property | Meaning |
|---|---|
id | Stable artifact identifier within the package. |
kind | database-schema, content, emails, i18n, or source. |
format | Required database-schema representation: prisma or drizzle. |
dialect | Required for Drizzle schema artifacts; currently postgresql. |
source / target | Package-relative source and default application destination. |
variant | Optional schema or output variant selected by application configuration. |
ejectable | Whether ownership may move to the application. |
securityCritical | Prevents ejection and keeps updates package-managed. |
hash | SHA-256 integrity check for the published source. |
When packages is omitted from an artifact target, the CLI surveys installed @playstack/* dependencies and uses emitters that declare the requested kind. An explicit package list becomes an allowlist and causes missing or invalid manifests to fail instead of being skipped.
For database schemas, the configured target adapter must match the artifact format. Drizzle targets additionally require matching PostgreSQL dialect metadata, exported schema symbols, resolvable copied imports, and collision-free filenames. The CLI materializes source only: Prisma, Drizzle Kit, or the application remains responsible for client generation, migrations, pushes, and introspection.
For an established Prisma application, run the read-only database compatibility command before synchronization. It reports incoming logical and physical names, existing declarations, artifact-to-artifact collisions, and field-level satisfaction findings. Continue with Existing schema adoption when the application already owns relevant tables.
Configure lazily
An artifact command can establish a missing target interactively without requiring a complete playstack init first. The CLI shows the proposed relative path and records it in playstack.json before synchronization.
In non-interactive or check mode, a missing target is reported as configuration drift. The CLI never guesses a write destination in CI.
Managed-file ownership
Managed files remain package-owned. The CLI records their source and content hashes under .playstack, then compares those hashes before every write.
- A clean second sync is a no-op.
- An upstream change updates an unmodified managed copy.
- A local edit is reported as unsafe and is not silently overwritten.
- A removed upstream artifact is removed only when its installed copy still matches the recorded hash.
Commit the managed output and .playstack state. Builds can then consume ordinary repository files without requiring the CLI or package registry at runtime.
If the application needs to own and modify an eligible source artifact, continue with Ejection and merging.
