Compatibility and upgrades

Flexkit’s framework quickstarts cover Next.js, Astro, and TanStack Start. Each application needs its framework adapter, React integration, @flexkit/studio and @flexkit/schema, the single @flexkit/studio/styles.css stylesheet, and a server-capable deployment.

Package consolidation

Install only @flexkit/studio and @flexkit/schema, plus @flexkit/cli. Desk, Asset Manager, Explorer, and AI are built into @flexkit/studio; the @flexkit/desk, @flexkit/asset-manager, @flexkit/explorer, and @flexkit/ai packages are deprecated and should be removed. When upgrading an application from the separate packages:

1. Remove the four app packages and their stylesheet imports; keep @flexkit/studio/styles.css.
2. Import defineConfig and defineEntity from @flexkit/schema in flexkit.config.ts, delete flexkit.studio.tsx, and drop basePath, extensions, commands, and icon from the configuration.
3. Replace hidden and readOnly callbacks with booleans, and replace icon components with Lucide icon names such as 'Tag'.
4. Mount <FlexkitStudio projectIds={['your-project-id']} basename="/studio" />; basename replaces basePath, and the host no longer imports the configuration.
5. Run flexkit deploy. Studio renders the deployed schema, so an updated configuration is invisible until it is deployed.

Record your release set

Keep the installed framework, React, @flexkit/studio, @flexkit/schema, and CLI versions in your lockfile and release notes. A repository checkout version is not proof that the same package was published or deployed to your project.

Upgrade workflow

1. Review package release notes and exported type changes.
2. Upgrade in a development application with a separate test project.
3. Build the client and server routes together.
4. Deploy the schema, then verify login, deep links, data reads/writes, scoped fields, and the app rail.
5. Check custom tools and any code using Studio hooks against the installed public types.
6. Deploy the required schema and application changes in the intended order.

If a documented export is absent, inspect the installed package version and entry point before using private source imports as a workaround. Report a reproducible mismatch through support.

Locally validated framework builds

The shared tutorial configuration builds with Next.js 16.3.1, Astro 7.1.6 with React integration 6.0.2 and a Node adapter, and TanStack Start/Router 1.132.0 with Vite 7.1.7. These build checks use React 19.2.7 and the package set in the quickstarts. Authentication, schema deployment, and saved-data verification additionally require a live project.

CLI configuration loading

The CLI loads flexkit.config.ts (.js and .mjs are also accepted). A .tsx or .jsx configuration is refused with migration guidance: the configuration is pure data and must not import React or Studio code. At deploy time the CLI compiles each attribute’s validation to JSON Schema and rejects fragments it cannot express (refine, transform, z.date, and similar) at schema[i].attributes[j].validation, and rejects entities that reference a menu group missing from menuGroups. See schema configuration for the supported validation subset.