Installation

This guide covers everything you need to install and configure Strapi2Front in your project.

System Requirements

Node.js

Version 18.0.0 or higher required

Strapi

Strapi v4 or v5 instance (local or remote)

Package Manager

npm, pnpm, yarn, or bun

TypeScript (Optional)

Works with both TypeScript and JavaScript projects

Installation Methods

Interactive Setup (Recommended)

The easiest way to get started is using the interactive init command:

npx strapi2front@latest init

pnpm dlx strapi2front@latest init

yarn dlx strapi2front@latest init

bunx strapi2front@latest init

This will:

Detect your project configuration (framework, TypeScript, package manager)
Prompt for Strapi connection details (URL, token, version)
Create configuration file (strapi.config.ts or strapi.config.js)
Set up environment variables (.env and .env.example)
Install dependencies (optional)

The init command is safe to re-run. It won’t overwrite existing environment variables.

Manual Installation

If you prefer manual setup:

Install the package

Add Strapi2Front as a dev dependency:

npm install -D strapi2front
npm install @strapi/client

pnpm add -D strapi2front
pnpm add @strapi/client

yarn add -D strapi2front
yarn add @strapi/client

bun add -D strapi2front
bun add @strapi/client

strapi2front is a dev dependency (used for code generation)
@strapi/client is a runtime dependency (used by generated code)

Create configuration file

Create strapi.config.ts (or .js for JavaScript projects):

TypeScript
JavaScript (ESM)
JavaScript (CommonJS)

strapi.config.ts

import { defineConfig } from "strapi2front";

export default defineConfig({
  // Strapi connection
  url: process.env.STRAPI_URL || "http://localhost:1337",
  token: process.env.STRAPI_SYNC_TOKEN || process.env.STRAPI_TOKEN,
  
  // API prefix (default: "/api")
  apiPrefix: "/api",
  
  // Output format: "typescript" (.ts) or "jsdoc" (.js with JSDoc)
  outputFormat: "typescript",
  
  // Output configuration
  output: {
    path: "src/strapi",
  },
  
  // Features to generate
  features: {
    types: true,       // TypeScript interfaces
    services: true,    // Service functions
    actions: true,     // Framework actions (Astro, Next.js, etc.)
    schemas: true,     // Zod validation schemas
    upload: false,     // File upload helpers
  },
  
  // Strapi version
  strapiVersion: "v5",
});

strapi.config.js

// @ts-check
import { defineConfig } from "strapi2front";

export default defineConfig({
  // Strapi connection
  url: process.env.STRAPI_URL || "http://localhost:1337",
  token: process.env.STRAPI_SYNC_TOKEN || process.env.STRAPI_TOKEN,
  
  // API prefix (default: "/api")
  apiPrefix: "/api",
  
  // Output format: "typescript" (.ts) or "jsdoc" (.js with JSDoc)
  outputFormat: "jsdoc",
  
  // Module type: "esm" or "commonjs" (auto-detected if not specified)
  moduleType: "esm",
  
  // Output configuration
  output: {
    path: "src/strapi",
  },
  
  // Features to generate
  features: {
    types: true,       // JSDoc type definitions
    services: true,    // Service functions with JSDoc
    actions: false,    // Actions require TypeScript
    schemas: true,     // Zod validation schemas
    upload: false,     // File upload helpers
  },
  
  // Strapi version
  strapiVersion: "v5",
});

strapi.config.js

// @ts-check
const { defineConfig } = require("strapi2front");

module.exports = defineConfig({
  // Strapi connection
  url: process.env.STRAPI_URL || "http://localhost:1337",
  token: process.env.STRAPI_SYNC_TOKEN || process.env.STRAPI_TOKEN,
  
  // API prefix (default: "/api")
  apiPrefix: "/api",
  
  // Output format: "typescript" (.ts) or "jsdoc" (.js with JSDoc)
  outputFormat: "jsdoc",
  
  // Output configuration
  output: {
    path: "src/strapi",
  },
  
  // Features to generate
  features: {
    types: true,       // JSDoc type definitions
    services: true,    // Service functions with JSDoc
    actions: false,    // Actions require TypeScript
    schemas: true,     // Zod validation schemas
    upload: false,     // File upload helpers
  },
  
  // Strapi version
  strapiVersion: "v5",
});

Set up environment variables

Create or update your .env file:

.env

# Strapi URL
STRAPI_URL=http://localhost:1337

# Sync token: Used by strapi2front to sync schema (development only)
# Permissions: content-type-builder (getContentTypes, getComponents), i18n (listLocales)
# IMPORTANT: Do NOT deploy this token to production
STRAPI_SYNC_TOKEN=

# Frontend token: Used by your app to fetch content (production)
# Configure with only the permissions your app needs
STRAPI_TOKEN=

Create .env.example for your repository:

.env.example

# Strapi URL
STRAPI_URL=http://localhost:1337

# Sync token: Used by strapi2front to sync schema (development only)
# Permissions: content-type-builder (getContentTypes, getComponents), i18n (listLocales)
# IMPORTANT: Do NOT deploy this token to production
STRAPI_SYNC_TOKEN=

# Frontend token: Used by your app to fetch content (production)
# Configure with only the permissions your app needs
STRAPI_TOKEN=

Add .env to your .gitignore to avoid committing sensitive tokens:

.gitignore

.env
.env.local

Strapi API Token Setup

Strapi2Front requires an API token with specific permissions to read your content type schema.

Create API Token in Strapi

Navigate to your Strapi admin panel:Settings > API Tokens > Create new API Token

Configure Token Settings

Strapi v5
Strapi v4

Token name: strapi2front-sync
Token type: Custom
Token duration: Unlimited (for development)

Permissions:

✅ Content-type-builder
- Components: getComponents, getComponent
- Content-types: getContentTypes, getContentType
✅ I18n (if using localization)
- Locales: listLocales

Name: strapi2front-sync
Token type: Custom
Duration: Unlimited (for development)

Permissions:

✅ Content-type-builder
- getContentTypes
- getContentType
- getComponents
- getComponent
✅ I18n (if using localization)
- listLocales

Save and Copy Token

Click Save and copy the generated token immediately.

Strapi only shows the token once. If you lose it, you’ll need to create a new one.

Add it to your .env file:

STRAPI_SYNC_TOKEN=your-generated-token-here

Why two tokens?

STRAPI_SYNC_TOKEN: Used by the CLI to read your schema (development only, should NOT be deployed)
STRAPI_TOKEN: Used by your app to fetch content (production, with limited read-only permissions)

The CLI will use STRAPI_SYNC_TOKEN if available, otherwise falls back to STRAPI_TOKEN.

File Upload Token (Optional)

If you enable the upload feature, you’ll need an additional token for file uploads:

Create Upload Token

In Strapi admin: Settings > API Tokens > Create new API Token

Token name: upload-token
Token type: Custom
Duration: As needed
Permissions:
- ✅ Upload
  - upload (only)
- ❌ No delete or update permissions (security best practice)

Add to Environment

Add both the URL and token:

.env

# Public URL for browser-side uploads
PUBLIC_STRAPI_URL=http://localhost:1337

# Upload token: Create in Strapi Admin > Settings > API Tokens
# Set permissions: Upload > upload (only, no delete/update)
PUBLIC_STRAPI_UPLOAD_TOKEN=your-upload-token-here

The PUBLIC_ prefix makes these variables available in client-side code (framework-specific naming may vary).

Verify Installation

Run the sync command to verify everything is set up correctly:

npx strapi2front sync

You should see output like:

┌  strapi2front sync
│
◇  Configuration loaded
◇  Version detection complete
│  Strapi v5
◇  Schema fetched: 5 collections, 2 singles, 8 components
◇  Generated 45 files
│
├  Sync complete!
│  Generated 45 files in src/strapi
│
│  Files generated:
│    src/strapi/collections/article/types.ts
│    src/strapi/collections/article/schemas.ts
│    src/strapi/collections/article/service.ts
│    src/strapi/collections/article/actions.ts
│    ... and 41 more
│
│  Docs: https://strapi2front.dev/docs
│
└  Types, Services, Schemas, Actions ready to use!

If you encounter any errors, check the CLI Reference for troubleshooting common issues.

Framework-Specific Setup

Astro

Install Astro dependencies

npm install @astrojs/node

Enable server output

If using Astro Actions, ensure your astro.config.mjs has:

astro.config.mjs

import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server', // or 'hybrid'
  adapter: node({
    mode: 'standalone'
  }),
});

Configure environment variables

Astro uses PUBLIC_ prefix for client-side variables:

.env

STRAPI_URL=http://localhost:1337
STRAPI_SYNC_TOKEN=sync-token-here
STRAPI_TOKEN=frontend-token-here
PUBLIC_STRAPI_URL=http://localhost:1337
PUBLIC_STRAPI_UPLOAD_TOKEN=upload-token-here

Next.js

Configure environment variables

Next.js uses NEXT_PUBLIC_ prefix for client-side variables:

.env.local

STRAPI_URL=http://localhost:1337
STRAPI_SYNC_TOKEN=sync-token-here
STRAPI_TOKEN=frontend-token-here
NEXT_PUBLIC_STRAPI_URL=http://localhost:1337
NEXT_PUBLIC_STRAPI_UPLOAD_TOKEN=upload-token-here

Update strapi.config.ts

Point output to your src/lib directory:

strapi.config.ts

export default defineConfig({
  // ...
  output: {
    path: "src/lib/strapi",
  },
});

Nuxt

Configure environment variables

Nuxt uses NUXT_PUBLIC_ prefix:

.env

STRAPI_URL=http://localhost:1337
STRAPI_SYNC_TOKEN=sync-token-here
STRAPI_TOKEN=frontend-token-here
NUXT_PUBLIC_STRAPI_URL=http://localhost:1337
NUXT_PUBLIC_STRAPI_UPLOAD_TOKEN=upload-token-here

SvelteKit

Configure environment variables

SvelteKit uses PUBLIC_ prefix:

.env

STRAPI_URL=http://localhost:1337
STRAPI_SYNC_TOKEN=sync-token-here
STRAPI_TOKEN=frontend-token-here
PUBLIC_STRAPI_URL=http://localhost:1337
PUBLIC_STRAPI_UPLOAD_TOKEN=upload-token-here

NPM Scripts (Optional)

Add convenient scripts to your package.json:

package.json

{
  "scripts": {
    "strapi:init": "strapi2front init",
    "strapi:sync": "strapi2front sync",
    "strapi:sync:force": "strapi2front sync --force",
    "strapi:sync:types": "strapi2front sync --types-only"
  }
}

Now you can use:

npm run strapi:sync

CI/CD Integration

To sync types in your CI/CD pipeline:

name: Sync Strapi Types

on:
  workflow_dispatch:
  schedule:
    - cron: '0 2 * * *' # Daily at 2am

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      
      - name: Install dependencies
        run: npm ci
      
      - name: Sync Strapi schema
        env:
          STRAPI_URL: ${{ secrets.STRAPI_URL }}
          STRAPI_SYNC_TOKEN: ${{ secrets.STRAPI_SYNC_TOKEN }}
        run: npx strapi2front sync
      
      - name: Commit changes
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add .
          git diff --staged --quiet || git commit -m "chore: sync Strapi types"
          git push

sync-strapi:
  image: node:20
  only:
    - schedules
  script:
    - npm ci
    - npx strapi2front sync
    - |
      git config --global user.email "gitlab@example.com"
      git config --global user.name "GitLab CI"
      git add .
      git diff --staged --quiet || git commit -m "chore: sync Strapi types"
      git push https://oauth2:${CI_JOB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git HEAD:${CI_COMMIT_REF_NAME}
  variables:
    STRAPI_URL: ${STRAPI_URL}
    STRAPI_SYNC_TOKEN: ${STRAPI_SYNC_TOKEN}

Next Steps

Quick Start

Get started with your first query

Configuration

Explore all configuration options

CLI Reference

Learn all available commands

Guides

Learn about types, services, and schemas

Get Started

Configuration

Guides

Framework Integrations

Installation

Installation

System Requirements

Node.js

Strapi

Package Manager

TypeScript (Optional)

Installation Methods

Interactive Setup (Recommended)

Manual Installation

Strapi API Token Setup

File Upload Token (Optional)

Verify Installation

Framework-Specific Setup

Astro

Next.js

Nuxt

SvelteKit

NPM Scripts (Optional)

CI/CD Integration

Next Steps

Quick Start

Configuration

CLI Reference

Guides

​Installation

​System Requirements

Node.js

Strapi

Package Manager

TypeScript (Optional)

​Installation Methods

​Interactive Setup (Recommended)

​Manual Installation

​Strapi API Token Setup

​File Upload Token (Optional)

​Verify Installation

​Framework-Specific Setup

​Astro

​Next.js

​Nuxt

​SvelteKit

​NPM Scripts (Optional)

​CI/CD Integration

​Next Steps

Quick Start

Configuration

CLI Reference

Guides

Installation

System Requirements

Installation Methods

Interactive Setup (Recommended)

Manual Installation

Strapi API Token Setup

File Upload Token (Optional)

Verify Installation

Framework-Specific Setup

Astro

Next.js

Nuxt

SvelteKit

NPM Scripts (Optional)

CI/CD Integration

Next Steps