Next.js Quickstart

Create a new Flexkit Studio in a Next.js application and run it locally.

Most teams do not need to self-host. The desktop app and flexkit.app run the same Studio with nothing to install or deploy. Self-host when you want Studio inside your own application, on your own domain, or next to custom tools you develop locally. These guides are for developers.

Before you start

Use Node.js 22 or later and a package manager. Create a Flexkit project (the Start from scratch option fits best), copy its Project ID from the Dashboard, and ensure your account can deploy its schema. New projects let the agent manage the schema, which refuses flexkit deploy; an owner switches the project to Managed from code under Settings → General → Schema Management first. 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 Next.js project

pnpm

pnpm create next-app@latest my-flexkit-app --yes
cd my-flexkit-app

npm

npx create-next-app@latest my-flexkit-app --yes
cd my-flexkit-app

yarn

yarn create next-app@latest my-flexkit-app --yes
cd my-flexkit-app

bun

bun create next-app@latest my-flexkit-app --yes
cd my-flexkit-app

Install Flexkit Studio packages

pnpm

pnpm add @flexkit/studio @flexkit/schema

npm

npm install @flexkit/studio @flexkit/schema

yarn

yarn add @flexkit/studio @flexkit/schema

bun

bun add @flexkit/studio @flexkit/schema

Create the Flexkit configuration

Create a flexkit.config.ts file in the root of your project. This file is pure data with no React or JSX: the CLI deploys it, and the Studio renders the deployed result.

flexkit.config.ts

import { defineConfig, defineEntity } from '@flexkit/schema';
 
const categories = defineEntity({
  name: 'category',
  plural: 'categories',
  display: 'name',
  menu: { label: 'Categories', icon: 'Tag' },
  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', icon: 'ShoppingCart' },
  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',
  scopes: [{ name: 'default', label: 'Default', isDefault: true }],
  schema: [products, categories],
});

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

local fields like product names, descriptions, prices, and category labels use the currently selected scope in Studio. If a local field has no value in the selected scope, the default scope value is used.

Create the API route handler and Studio page

Create a new API route handler to serve the Flexkit API and a Studio page to render the Flexkit Studio interface. Create the following file structure:

- - - - route.ts
- - - page.tsx

app/api/flexkit/[...path]/route.ts

import { createFlexkitApiHandler } from '@flexkit/studio/nextjs';
import { NextResponse } from 'next/server';
import { cookies, headers } from 'next/headers';
 
const flexkitHandler = createFlexkitApiHandler({
  NextResponse,
  cookies,
  headers,
});
 
export const runtime = 'nodejs';
 
export const { GET, POST, PUT, PATCH, DELETE } = flexkitHandler;

app/studio/[[...index]]/page.tsx

 
import { JSX } from 'react';
import '@flexkit/studio/styles.css';
import { FlexkitStudio } from '@flexkit/studio';
 
export default function Page(): JSX.Element | null {
  return <FlexkitStudio projectIds={['your-project-id']} basename="/studio" />;
}

Deploy your data schema

Install the Flexkit CLI to deploy your data schema.

flexkit login
flexkit whoami
flexkit deploy

The Studio renders the deployed schema, not the local file. Run flexkit deploy again after every change to flexkit.config.ts; until the first deployment the project has no entities, so Desk is empty.

Run Your Project

Start the development server:

pnpm

pnpm dev

npm

npm run dev

yarn

yarn dev

bun

bun dev

Open your browser and navigate to http://localhost:3000/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. An empty Desk means flexkit deploy has not run for that project ID yet; a Project not found screen means the project ID is wrong or the API handler route is not mounted; a No access screen means your account is not a member of the project. Continue with the sample store tour to see what the agent can do, then production deployment.