Installation

This guide covers setting up a new Catmint project from scratch, as well as adding Catmint to an existing application.

System Requirements

• Node.js 20 or later
• pnpm 9 or later
• React 19 or later (installed as a peer dependency)

Catmint targets ES2022 and uses TypeScript in strict mode. Make sure your environment supports modern JavaScript features such as top-level await and structuredClone.

Create a New Project

The fastest way to get started is with create-catmint, which scaffolds a fully configured project:

pnpm create catmint my-app

The scaffolder will prompt you to choose a mode (fullstack, frontend, or backend) and a deployment adapter. Once it finishes, start the development server:

cd my-app
pnpm install
pnpm dev

Your application will be available at http://localhost:5173 by default.

Manual Installation

If you prefer to set things up yourself, install the core packages manually.

1. Initialize the project

mkdir my-app && cd my-app
pnpm init

2. Install dependencies

pnpm add catmint react react-dom
pnpm add -D @catmint/vite @catmint/cli typescript @types/react @types/react-dom

3. Create the config file

Create catmint.config.ts in the project root. Configuration is defined with the defineConfig helper exported from catmint/config:

// catmint.config.ts
import { defineConfig } from 'catmint/config'

export default defineConfig({
  mode: 'fullstack',
})

4. Create a TypeScript config

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist"
  },
  "include": ["app", "catmint.config.ts"]
}

5. Add scripts to package.json

{
  "scripts": {
    "dev": "catmint dev",
    "build": "catmint build",
    "start": "catmint start"
  }
}

6. Create your first page

mkdir -p app
touch app/page.tsx

// app/page.tsx
export default function HomePage() {
  return <h1>Hello from Catmint</h1>
}

7. Start the dev server

pnpm dev

Adding to an Existing Project

Catmint can be added to an existing React or Vite project. Install the same dependencies listed above, create a catmint.config.ts, and move your entry point into the app/ directory.

If you already have a Vite config, note that Catmint provides its own Vite plugin via the @catmint/vite package. Add it to your vite.config.ts:

// vite.config.ts
import { defineConfig } from 'vite'
import catmint from '@catmint/vite'

export default defineConfig({
  plugins: [catmint()],
})

Deployment Adapters

To deploy your application, install the adapter for your target platform:

Then reference the adapter in your config:

// catmint.config.ts
import { defineConfig } from 'catmint/config'
import node from '@catmint/adapter-node'

export default defineConfig({
  mode: 'fullstack',
  adapter: node(),
})

Subpath Imports

Catmint does not provide a barrel catmint export. All functionality is accessed through subpath imports:

import { defineConfig } from 'catmint/config'
import { defineRoutes } from 'catmint/routing'
import { useParams, useSearch } from 'catmint/hooks'
import { createServerFn } from 'catmint/server'
import { cookies } from 'catmint/cookies'
import { Head } from 'catmint/head'

This design keeps bundles small and makes it explicit where each API comes from.

Next: Quick Start →