Astro Quickstart

Create a new Flexkit Studio in an Astro application and run it locally.

Before you start

Use Node.js 22 or later and a package manager. Create a Flexkit project, copy its Project ID, and ensure your account can deploy its schema. These examples use a project you can safely populate with synthetic data.

Keep the generated application’s package versions locked. See compatibility when upgrading. Use the directory layout shown here; adjust relative imports if you choose a src directory in Next.js.

Create a new Astro project with React support

pnpm

pnpm create astro@latest my-flexkit-app --add react && cd my-flexkit-app

npm

npm create astro@latest -- my-flexkit-app --add react && cd my-flexkit-app

yarn

yarn create astro my-flexkit-app && cd my-flexkit-app && yarn astro add react

bun

bun create astro my-flexkit-app && cd my-flexkit-app && bun astro add react

Install Flexkit Studio packages

pnpm

pnpm add @flexkit/studio @flexkit/desk @flexkit/asset-manager @flexkit/explorer @flexkit/ai

npm

npm install @flexkit/studio @flexkit/desk @flexkit/asset-manager @flexkit/explorer @flexkit/ai

yarn

yarn add @flexkit/studio @flexkit/desk @flexkit/asset-manager @flexkit/explorer @flexkit/ai

bun

bun add @flexkit/studio @flexkit/desk @flexkit/asset-manager @flexkit/explorer @flexkit/ai

Create the Flexkit configuration

Create a flexkit.config.ts file in the root of your project. This file defines the project schema used by the CLI. The separate Studio configuration below registers browser extensions.

flexkit.config.ts

import { defineConfig, defineEntity } from '@flexkit/studio';
 
const categories = defineEntity({
  name: 'category',
  plural: 'categories',
  display: 'name',
  menu: { label: 'Categories' },
  attributes: [
    { name: 'name', label: 'Name', scope: 'local', dataType: 'string', inputType: 'text', searchable: true },
    { name: 'slug', label: 'Slug', scope: 'global', dataType: 'string', inputType: 'text', unique: true },
  ],
});
 
const products = defineEntity({
  name: 'product',
  plural: 'products',
  display: 'name',
  menu: { label: 'Products' },
  attributes: [
    { name: 'name', label: 'Name', scope: 'local', dataType: 'string', inputType: 'text', searchable: true },
    {
      name: 'sku',
      label: 'SKU',
      scope: 'global',
      dataType: 'string',
      inputType: 'text',
      unique: true,
      searchable: true,
    },
    { name: 'price', label: 'Price', scope: 'local', dataType: 'float', inputType: 'number' },
    { name: 'image', label: 'Image', scope: 'global', dataType: 'asset', inputType: 'asset' },
    { name: 'status', label: 'Status', scope: 'global', dataType: 'string', inputType: 'text', defaultValue: 'draft' },
    {
      name: 'category',
      label: 'Category',
      scope: 'relationship',
      dataType: 'string',
      inputType: 'relationship',
      relationship: { mode: 'single', field: 'name', entity: 'category' },
    },
  ],
});
 
export default defineConfig({
  title: 'Catalog Studio',
  projectId: 'your-project-id',
  basePath: '/studio',
  scopes: [{ name: 'default', label: 'Default', isDefault: true }],
  schema: [products, categories],
});

Keep this configuration free of browser extension imports so the CLI can load it. Create a separate Studio configuration:

flexkit.studio.tsx

import { defineConfig } from '@flexkit/studio';
import { Desk } from '@flexkit/desk';
import { AssetManager } from '@flexkit/asset-manager';
import { Explorer } from '@flexkit/explorer';
import { AI } from '@flexkit/ai';
import project from './flexkit.config';
 
export default defineConfig({
  ...project,
  extensions: [Desk(), AssetManager(), Explorer(), AI()],
});

Important: Replace 'your-project-id' with the unique project ID of your Flexkit project.

local fields use the selected scope in Studio. When a local field has no value for the active scope, Studio falls back to the default scope value.

Enable React and server rendering

Add Astro’s React integration and Node adapter:

pnpm astro add react node

Confirm the generated configuration contains React and a server adapter:

astro.config.mjs

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import node from '@astrojs/node';
 
export default defineConfig({
  integrations: [react()],
  output: 'server',
  adapter: node({ mode: 'standalone' }),
});

Create the API route handler

Create a new API route handler to serve the Flexkit API. Create the following file structure:

- - - - [...path].ts

src/pages/api/flexkit/[...path].ts

import { createFlexkitAstroHandler } from '@flexkit/studio/astro';
 
export const prerender = false;
 
const handler = createFlexkitAstroHandler();
 
export const GET = handler;
export const POST = handler;
export const PUT = handler;
export const PATCH = handler;
export const DELETE = handler;

Create the Studio page and component

Create a new Studio component and a page to render the Flexkit Studio interface. Create the following file structure:

- - studio.tsx
- - - [...path].astro

src/components/studio.tsx

import '@flexkit/studio/styles.css';
import '@flexkit/desk/styles.css';
import '@flexkit/asset-manager/styles.css';
import '@flexkit/explorer/styles.css';
import '@flexkit/ai/styles.css';
import { FlexkitStudio } from '@flexkit/studio';
import config from '../../flexkit.studio';
 
export default function Studio() {
  return <FlexkitStudio config={config} />;
}

src/pages/studio/[...path].astro

---
import Studio from '../../components/studio';
---
 
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Flexkit Studio</title>
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
  </head>
  <body>
    <Studio client:only="react" />
  </body>
</html>

Deploy your data schema

Install the Flexkit CLI to deploy your data schema.

flexkit login
flexkit whoami
flexkit deploy

Run Your Project

Start the development server:

pnpm

pnpm run dev

npm

npm run dev

yarn

yarn run dev

bun

bun run dev

Open your browser and navigate to http://localhost:4321/studio

Confirm your first success

Sign into Studio with the account that has access to the configured project. Open Desk, create a Category and Product, save, and reopen the record. Open Explorer and run the tutorial read. The record ID and global SKU should agree with the saved record.

If the UI loads but data does not, check the project ID, completed schema deployment, role/spaces, and API handler route. Missing styles usually indicate an omitted extension stylesheet. Continue with your first workflow, then production deployment.