Migrate from v0.8.x to v1.0.0

This guide covers @mauriciodmo/framekit 0.8.x → 1.0.0. Update @mauriciodmo/create-framekit from 0.8.x to 1.0.0 only when scaffolding a new project; the creator does not update existing projects.

Breaking change

FrameKit 1.0.0 makes authentication opt-in. If FRAMEKIT_AUTH_ENABLED is absent or false, /editor and /brand are available without a session, /login redirects to /editor, /settings and the access API return not found, and image rendering requires no credentials. Any client that can reach the server can use Studio and the image API in this mode.

Set FRAMEKIT_AUTH_ENABLED=true before deploying 1.0.0 when the deployment must keep Studio and image rendering protected. Do not rely on NODE_ENV, existing credentials, or a SQLite file to enable authentication.

Keep a deployment protected

1. Back up the project configuration and any existing FrameKit data.

2. Add this variable to the environment used by the actual runtime, before installing or starting 1.0.0:

   FRAMEKIT_AUTH_ENABLED=true

3. If the authentication database has no administrator yet, also provide a valid FRAMEKIT_ADMIN_PASSWORD to bootstrap the first administrator. Bootstrap variables do not replace users in an existing database.

4. Keep FRAMEKIT_DATABASE_PATH pointed at the same writable, persistent database location when authentication data must survive restarts. The default is .framekit-data/framekit.sqlite.

5. Update the existing project’s @mauriciodmo/framekit dependency to 1.0.0, install dependencies, then regenerate and verify the project before deployment:

   pnpm install
   pnpm exec framekit generate
   pnpm exec framekit check
   pnpm build

6. After deployment, verify that an unauthenticated request to /editor redirects to /login, the configured administrator can sign in, and image rendering rejects requests without a valid session or API token.

If rollback is required, restore the previous package version and runtime configuration from the backup. Keep the 1.0.0 database untouched; do not assume an older package can read data created by a newer release.

Intentionally use open mode

If Studio and image rendering are meant to be reachable without a login, leave the variable unset or set FRAMEKIT_AUTH_ENABLED=false. Treat both surfaces as public to clients that can reach the process. The renderer’s input, image, browser, timeout, and cleanup protections remain enabled; development asset uploads still require same-origin requests.

Open mode does not initialize the access database. Switching authentication off later does not delete users, sessions, or API tokens. To enable authentication after using open mode, set FRAMEKIT_AUTH_ENABLED=true and a valid FRAMEKIT_ADMIN_PASSWORD so the first administrator can be created.

Other contract changes

This guide covers the authentication default. If the project has not yet adopted the current template or generated-file contract, also follow the current contract migration checklist.