Configuration Reference

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
});

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

export default defineConfig({
  // Your configuration  
});

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

module.exports = defineConfig({
  // Your configuration
});

The defineConfig helper provides TypeScript autocomplete and validation.

Connection Options

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"

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.

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

'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

'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.

'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".

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.

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

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

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"

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

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.

boolean

default:false

Use advanced relation format with connect/disconnect/set operations instead of simple ID arrays.

Simple (default)
Advanced

{ tags: ["id1", "id2"] }

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

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

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.

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,
});

import { defineConfig } from "strapi2front";

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

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

export default defineConfig({
  url: process.env.STRAPI_URL || "http://localhost:1337",
  token: process.env.STRAPI_SYNC_TOKEN || process.env.STRAPI_TOKEN,
  
  outputFormat: "jsdoc",
  moduleType: "esm",
  
  output: {
    path: "src/strapi",
  },
  
  features: {
    types: true,
    services: true,
    actions: false, // Not supported in JSDoc
    schemas: true,
    upload: true,
  },
  
  strapiVersion: "v5",
});

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:

strapi.config.ts
strapi.config.js
strapi.config.mjs
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);
}

​Configuration File

​Connection Options

​Strapi Version

​Output Configuration

​Features

​Schema Options

​Advanced Options

​Complete Example

​Type Definitions

​Config File Location

​Environment Variables

​Validation

Configuration File

Connection Options

Strapi Version

Output Configuration

Features

Schema Options

Advanced Options

Complete Example

Type Definitions

Config File Location

Environment Variables

Validation