Skip to main content
The strapi.config.ts file controls how strapi2front connects to your Strapi backend and generates code. Created by strapi2front init, it’s validated with Zod for type safety.

​
Configuration File

import { defineConfig } from "strapi2front";

export default defineConfig({
  // Your configuration
});
The defineConfig helper provides TypeScript autocomplete and validation.

​
Connection Options

​
url
string
required
Strapi backend URL. Must be a valid URL.Example: "http://localhost:1337" or "https://api.example.com"Typically loaded from environment:
url: process.env.STRAPI_URL || "http://localhost:1337"
​
token
string
API token for syncing schema from Strapi. Optional but recommended.Required permissions:
  • content-type-builder.getContentTypes
  • content-type-builder.getComponents
  • i18n.listLocales
Typically loaded from environment:
token: process.env.STRAPI_SYNC_TOKEN || process.env.STRAPI_TOKEN
The sync token should only be used in development. Never deploy it to production.
​
apiPrefix
string
default:"/api"
API prefix used in your Strapi configuration. Change if you customized Strapi’s REST API prefix.Example: "/api/v1" or "/custom-api"

​
Strapi Version

​
strapiVersion
'v4' | 'v5'
default:"v5"
Strapi major version. Affects schema parsing and type generation.
  • "v5" - Strapi 5.x (uses documentId, new relations format)
  • "v4" - Strapi 4.x (uses numeric id)
The CLI auto-detects version during sync and warns if there’s a mismatch.

​
Output Configuration

​
outputFormat
'typescript' | 'jsdoc'
default:"typescript"
Code output format.
  • "typescript" - Generate .ts files with TypeScript syntax
  • "jsdoc" - Generate .js files with JSDoc type annotations
Actions are only available in TypeScript mode. JSDoc projects can only generate types, services, schemas, and upload helpers.
​
moduleType
'esm' | 'commonjs'
Module system for JavaScript output (JSDoc only). Auto-detected from package.json if not specified.
  • "esm" - ES Modules (import/export)
  • "commonjs" - CommonJS (require/module.exports)
Only applies when outputFormat: "jsdoc".
​
output.path
string
default:"src/strapi"
Output directory for generated files, relative to project root.Example: "src/lib/strapi" or "generated/strapi"

​
Features

Control which files to generate. All features default to true except upload.
​
features.types
boolean
default:true
Generate TypeScript type definitions for all content types, components, and API responses.Generates:
  • Type interfaces for each content type
  • Component types
  • Relation types
  • API response wrappers
  • Locale types
​
features.services
boolean
default:true
Generate service classes for API calls (CRUD operations, queries, filters).Generates:
  • Service with methods like findMany(), findOne(), create(), update(), delete()
  • Typed query builders
  • Population helpers
  • Locale switching
​
features.actions
boolean
default:true
Generate framework-specific server actions (currently Astro only).Generates:
  • Type-safe server actions
  • Automatic validation
  • Error handling
Only available when outputFormat: "typescript"
​
features.schemas
boolean
Generate Zod validation schemas for form libraries (React Hook Form, TanStack Form, etc.).Default: true for TypeScript, false for JSDocGenerates:
  • Zod schemas for create/update operations
  • Field validation based on Strapi schema constraints
  • Enum validation
  • Required/optional field handling
​
features.upload
boolean
default:false
Generate file upload helpers for browser and server.Generates:
  • Public upload client for browser
  • Server action for secure uploads (framework-specific)
  • Type-safe upload methods
Environment variables required:
  • PUBLIC_STRAPI_URL
  • PUBLIC_STRAPI_UPLOAD_TOKEN

​
Schema Options

Customize validation schema generation.
​
schemaOptions.advancedRelations
boolean
default:false
Use advanced relation format with connect/disconnect/set operations instead of simple ID arrays.
{ tags: ["id1", "id2"] }
Advanced format supports:
  • connect - Add relations while preserving existing
  • disconnect - Remove specific relations
  • set - Replace all relations
  • locale - Target specific locale for i18n content
  • status - Target draft/published versions
  • position - Control ordering (before, after, start, end)
See Strapi Relations Docs

​
Advanced Options

​
options.includeDrafts
boolean
default:false
Include draft content types in generation. Only applies to content types with draftAndPublish enabled.When true, generated types will include draft-specific fields and methods.
​
options.strictTypes
boolean
default:false
Generate strict types with no optional fields. All fields marked as non-required in Strapi will still be required in TypeScript.
Use with caution - this can cause type mismatches with actual API responses.

​
Complete Example

import { defineConfig } from "strapi2front";

export default defineConfig({
  url: process.env.STRAPI_URL || "http://localhost:1337",
  token: process.env.STRAPI_SYNC_TOKEN,
});

​
Type Definitions

export interface StrapiIntegrateConfig {
  url: string;
  token?: string;
  apiPrefix: string;
  strapiVersion: "v4" | "v5";
  outputFormat: "typescript" | "jsdoc";
  moduleType?: "esm" | "commonjs";
  output: {
    path: string;
  };
  features: {
    types: boolean;
    services: boolean;
    actions: boolean;
    schemas?: boolean;
    upload: boolean;
  };
  schemaOptions: {
    advancedRelations: boolean;
  };
  options: {
    includeDrafts: boolean;
    strictTypes: boolean;
  };
}

export type StrapiIntegrateConfigInput = /* Zod input type with defaults */;

​
Config File Location

The CLI searches for config files in this order:
  1. strapi.config.ts
  2. strapi.config.js
  3. strapi.config.mjs
  4. strapi.config.cjs
Place your config file in the project root (same directory as package.json).

​
Environment Variables

The config loader automatically resolves environment variables from .env files using dotenv. Variables are loaded before config parsing. Supported patterns:
  • process.env.VARIABLE_NAME
  • Direct environment variable access
  • Fallback chains: process.env.VAR1 || process.env.VAR2 || "default"
Special handling:
  • token field: Automatically tries STRAPI_SYNC_TOKEN → STRAPI_TOKEN if not explicitly set

​
Validation

Configuration is validated using Zod with the configSchema. Invalid configurations will throw detailed error messages. 
import { configSchema } from 'strapi2front/core';

// Validate manually
const result = configSchema.safeParse(yourConfig);
if (!result.success) {
  console.error(result.error);
}