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 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.jsstrapi.config.mjsstrapi.config.cjs
Use TypeScript for autocomplete and validation while editing your config.
Connection Options Configure how strapi2front connects to your Strapi instance.
Base URL of your Strapi server (without /api suffix) url : "http://localhost:1337" url : process . env . STRAPI_URL
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 configSTRAPI_SYNC_TOKEN environment variableSTRAPI_TOKEN environment variable API prefix used by Strapi. Customize if you’ve changed the default in Strapi. apiPrefix : "/api" // default apiPrefix : "/strapi-api" // custom
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.
output.path
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 }
outputFormat
'typescript' | 'jsdoc'
default: "typescript"
Choose between TypeScript or JavaScript with JSDoc annotations. 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 */
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.
Generate TypeScript interfaces for all content types. features : { types : true , // generates types.ts files }
Generate API service functions with full CRUD operations. features : { services : true , // generates service.ts files }
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.
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.
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.
schemaOptions.advancedRelations
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 existingdisconnect - Remove specific relationsset - Replace all relationslocale - Target specific localestatus - Target draft/publishedposition - Control ordering (before, after, start, end) Include draft content types in generation. options : { includeDrafts : false , // skip draft content types }
Reserved for future use. Currently has no effect.
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 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:
.env (Development)
.env.production
# 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
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 ({}), });
Next Steps