Configuration File

The strapi.config.ts file is your central configuration for strapi2front. It controls how types, services, schemas, and actions are generated from your Strapi schema.

Quick Start

strapi.config.ts

import { defineConfig } from "strapi2front";

export default defineConfig({
  url: process.env.STRAPI_URL || "http://localhost:1337",
  token: process.env.STRAPI_TOKEN,
  
  output: {
    path: "src/strapi",
  },
  
  features: {
    types: true,
    services: true,
    schemas: true,
  },
});

File Location

Place your config file in your project root. strapi2front looks for these files in order:

strapi.config.ts (recommended)
strapi.config.js
strapi.config.mjs
strapi.config.cjs

Use TypeScript for autocomplete and validation while editing your config.

Connection Options

Configure how strapi2front connects to your Strapi instance.

string

required

Base URL of your Strapi server (without /api suffix)

url: "http://localhost:1337"
url: process.env.STRAPI_URL

string

API token for authentication. Required for fetching schema.

token: process.env.STRAPI_TOKEN

Never hardcode tokens in your config. Always use environment variables.

The token is read in this order:

token field in config
STRAPI_SYNC_TOKEN environment variable
STRAPI_TOKEN environment variable

string

default:"/api"

API prefix used by Strapi. Customize if you’ve changed the default in Strapi.

apiPrefix: "/api"  // default
apiPrefix: "/strapi-api"  // custom

'v4' | 'v5'

default:"v5"

Target Strapi version. Auto-detected during sync if not specified.

strapiVersion: "v5"  // Strapi 5.x
strapiVersion: "v4"  // Strapi 4.x

strapi2front auto-detects the version from your Strapi instance and warns you if there’s a mismatch.

Output Options

Control where and how files are generated.

string

default:"src/strapi"

Directory where generated files will be written.

output: {
  path: "src/strapi",          // default
  path: "app/lib/strapi",      // custom
  path: "generated/api",       // custom
}

'typescript' | 'jsdoc'

default:"typescript"

Choose between TypeScript or JavaScript with JSDoc annotations.

TypeScript
JSDoc

outputFormat: "typescript"  // generates .ts files

Generates:

export interface Article {
  id: number;
  title: string;
}

outputFormat: "jsdoc"  // generates .js files

Generates:

/**
 * @typedef {Object} Article
 * @property {number} id
 * @property {string} title
 */

'esm' | 'commonjs'

Module system for JSDoc output. Auto-detected from package.json if not specified.

outputFormat: "jsdoc",
moduleType: "esm",        // import/export
moduleType: "commonjs",   // require/module.exports

Only relevant when outputFormat: "jsdoc". TypeScript always uses ESM syntax.

Auto-detection rules:

Checks package.json for "type": "module"
Defaults to "commonjs" if not found

Feature Toggles

Enable or disable specific code generators. See Features for detailed documentation.

boolean

default:true

Generate TypeScript interfaces for all content types.

features: {
  types: true,  // generates types.ts files
}

boolean

default:true

Generate API service functions with full CRUD operations.

features: {
  services: true,  // generates service.ts files
}

boolean

default:true

Generate Astro Actions for server-side API calls.

features: {
  actions: true,  // generates actions.ts files (TypeScript only)
}

Actions are only generated when outputFormat: "typescript". They are skipped for JSDoc output.

boolean

Generate Zod validation schemas for form handling.

features: {
  schemas: true,  // generates schemas.ts files
}

Default value:

true when outputFormat: "typescript"
false when outputFormat: "jsdoc"

Zod schemas work best with TypeScript. For JSDoc projects, schemas are disabled by default.

boolean

default:false

Generate file upload helpers for browser and server.

features: {
  upload: true,  // generates upload-client.ts and upload-action.ts
}

See Features > Upload for setup details.

Schema Options

Configure how Zod schemas are generated.

boolean

default:false

Use advanced relation format with connect/disconnect/set operations.

Simple (default)
Advanced

schemaOptions: {
  advancedRelations: false,
}

Generates simple array format:

{
  tags: ["documentId1", "documentId2"]
}

schemaOptions: {
  advancedRelations: true,
}

Generates full Strapi v5 relation API:

{
  tags: {
    connect: [{ documentId: "id1" }],
    disconnect: ["id2"],
    set: [{ documentId: "id3" }],
  }
}

Supports:

connect - Add relations while preserving existing
disconnect - Remove specific relations
set - Replace all relations
locale - Target specific locale
status - Target draft/published
position - Control ordering (before, after, start, end)

See Strapi Relations API for complete documentation.

boolean

default:false

Include draft content types in generation.

options: {
  includeDrafts: false,  // skip draft content types
}

Reserved for future use. Currently has no effect.

boolean

default:false

Generate strict types with no optional fields.

options: {
  strictTypes: false,  // respect Strapi's required/optional
}

Reserved for future use. Currently has no effect.

Complete Example

strapi.config.ts

import { defineConfig } from "strapi2front";

export default defineConfig({
  // Connection
  url: process.env.STRAPI_URL || "http://localhost:1337",
  token: process.env.STRAPI_TOKEN,
  apiPrefix: "/api",
  strapiVersion: "v5",
  
  // Output
  outputFormat: "typescript",
  output: {
    path: "src/strapi",
  },
  
  // Features
  features: {
    types: true,
    services: true,
    actions: true,
    schemas: true,
    upload: false,
  },
  
  // Schema generation
  schemaOptions: {
    advancedRelations: true,
  },
});

Environment Variables

Recommended .env setup:

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

# Sync token: Used by strapi2front CLI (development only)
# Permissions needed: content-type-builder.getContentTypes, 
#                     content-type-builder.getComponents,
#                     i18n.listLocales
STRAPI_SYNC_TOKEN=your-sync-api-token-here

# Frontend token: Used by your app to fetch content
# Configure with only the permissions your app needs
STRAPI_TOKEN=your-frontend-api-token-here

# Upload token (if features.upload enabled)
# Permissions: upload.upload (only)
PUBLIC_STRAPI_UPLOAD_TOKEN=your-upload-token-here

# Production - only frontend token
STRAPI_URL=https://api.example.com
STRAPI_TOKEN=your-production-token

# NEVER deploy STRAPI_SYNC_TOKEN to production
# It has access to content-type-builder API

Security Best Practices:

Never hardcode tokens in your config file
Never commit .env to version control (add to .gitignore)
Never deploy STRAPI_SYNC_TOKEN to production
Use separate tokens with minimal permissions for each environment

Type Safety

The config uses Zod validation. Invalid configurations are caught immediately:

import { defineConfig } from "strapi2front";

export default defineConfig({
  url: "not-a-url",  // ❌ Error: url must be a valid URL
  strapiVersion: "v3",  // ❌ Error: must be "v4" or "v5"
});

Use defineConfig() to get autocomplete and validation in your editor.

Config Schema

The configuration is validated using this Zod schema:

packages/core/src/config/schema.ts

export const configSchema = z.object({
  url: z.string().url("url must be a valid URL"),
  token: z.string().min(1, "token is required").optional(),
  apiPrefix: z.string().default("/api"),
  strapiVersion: z.enum(["v4", "v5"]).default("v5"),
  outputFormat: z.enum(["typescript", "jsdoc"]).default("typescript"),
  moduleType: z.enum(["esm", "commonjs"]).optional(),
  
  output: z.object({
    path: z.string().default("src/strapi"),
  }).default({}),
  
  features: z.object({
    types: z.boolean().default(true),
    services: z.boolean().default(true),
    actions: z.boolean().default(true),
    schemas: z.boolean().optional(),
    upload: z.boolean().default(false),
  }).default({}),
  
  schemaOptions: z.object({
    advancedRelations: z.boolean().default(false),
  }).default({}),
  
  options: z.object({
    includeDrafts: z.boolean().default(false),
    strictTypes: z.boolean().default(false),
  }).default({}),
});

Get Started

Configuration

Guides

Framework Integrations

Quick Start

File Location

Connection Options

Output Options

Feature Toggles

Schema Options

Complete Example

Environment Variables

Type Safety

Config Schema

Next Steps

Features

Output Structure

​Quick Start

​File Location

​Connection Options

​Output Options

​Feature Toggles

​Schema Options

​Complete Example

​Environment Variables

​Type Safety

​Config Schema

​Next Steps

Features

Output Structure

Quick Start

File Location

Connection Options

Output Options

Feature Toggles

Schema Options

Complete Example

Environment Variables

Type Safety

Config Schema

Next Steps