Reference

Project Config Reference

The project.config.json file in the project root configures site-wide settings: URLs, icons, internationalization, breakpoints, fonts, component organization, and external libraries.

Full Example

{
  "siteUrl": "https://example.com",
  "icons": {
    "favicon": "/icons/favicon.ico",
    "appleTouchIcon": "/icons/apple-touch-icon.png"
  },
  "componentTypes": [
    { "id": "ui", "label": "UI", "color": "#3b82f6" },
    { "id": "shared", "label": "Shared", "color": "#bababa" },
    { "id": "custom", "label": "Custom", "color": "#daf50f" }
  ],
  "i18n": {
    "defaultLocale": "en",
    "locales": [
      {
        "code": "en",
        "name": "EN",
        "nativeName": "EN",
        "langTag": "en-US",
        "icon": "/icons/us.svg"
      },
      {
        "code": "pl",
        "name": "PL",
        "nativeName": "PL",
        "langTag": "pl-PL",
        "icon": "/icons/pl.svg"
      }
    ]
  },
  "breakpoints": {
    "tablet": 1024,
    "mobile": 540
  },
  "responsiveScales": {
    "enabled": true,
    "baseReference": 16,
    "fontSize": { "tablet": 0.8, "mobile": 0.7 },
    "padding": { "tablet": 0.75, "mobile": 0.5 },
    "margin": { "tablet": 0.7, "mobile": 0.45 },
    "gap": { "tablet": 0.65, "mobile": 0.4 }
  },
  "fonts": [
    {
      "path": "/fonts/Inter-VariableFont_opsz,wght.ttf",
      "family": "Inter",
      "weight": 400,
      "fontDisplay": "swap"
    }
  ],
  "componentCategories": {
    "Navigation": "shared",
    "Stack": "ui"
  }
}

Properties

siteUrl

Property	Type	Required	Description
`siteUrl`	`string`	No	Full URL of the deployed site

Used during static build to generate robots.txt and sitemap.xml. Include the protocol and domain without a trailing slash.

{
  "siteUrl": "https://example.com"
}

icons

Property	Type	Required	Description
`icons.favicon`	`string`	No	Path to favicon file
`icons.appleTouchIcon`	`string`	No	Path to Apple touch icon

Paths are relative to the project's public directory. During static build, <link> tags are generated in the HTML <head>.

{
  "icons": {
    "favicon": "/icons/favicon.ico",
    "appleTouchIcon": "/icons/apple-touch-icon.png"
  }
}

componentTypes

Property	Type	Required	Description
`componentTypes`	`ComponentType[]`	No	Categories for organizing components

Each component type has:

Field	Type	Description
`id`	`string`	Unique identifier
`label`	`string`	Display name in the editor
`color`	`string`	Hex color for visual distinction

{
  "componentTypes": [
    { "id": "ui", "label": "UI", "color": "#3b82f6" },
    { "id": "shared", "label": "Shared", "color": "#bababa" },
    { "id": "custom", "label": "Custom", "color": "#daf50f" }
  ]
}

componentCategories

Property	Type	Required	Description
`componentCategories`	`Record<string, string>`	No	Default category mapping for components

Keys are component names, values are component type IDs from componentTypes.

{
  "componentCategories": {
    "Navigation": "shared",
    "Footer": "shared",
    "Hero": "ui",
    "Stack": "ui",
    "PricingCard": "custom"
  }
}

i18n

Property	Type	Required	Description
`i18n`	`I18nConfig`	No	Internationalization configuration

Omit i18n entirely for single-language projects.

I18nConfig

Field	Type	Description
`defaultLocale`	`string`	Locale code used when no prefix is in the URL
`locales`	`LocaleConfig[]`	Array of supported locales

LocaleConfig

Field	Type	Required	Description
`code`	`string`	Yes	URL prefix and translation key (e.g., `"en"`, `"pl"`)
`name`	`string`	Yes	English name for admin UI (e.g., `"Polish"`)
`nativeName`	`string`	Yes	Native name for public UI (e.g., `"Polski"`)
`langTag`	`string`	Yes	BCP 47 language tag for SEO (e.g., `"pl-PL"`)
`icon`	`string`	No	Path to flag icon (e.g., `"/icons/flag-pl.svg"`)

{
  "i18n": {
    "defaultLocale": "en",
    "locales": [
      {
        "code": "en",
        "name": "English",
        "nativeName": "English",
        "langTag": "en-US",
        "icon": "/icons/us.svg"
      },
      {
        "code": "pl",
        "name": "Polish",
        "nativeName": "Polski",
        "langTag": "pl-PL",
        "icon": "/icons/pl.svg"
      },
      {
        "code": "de",
        "name": "German",
        "nativeName": "Deutsch",
        "langTag": "de-DE",
        "icon": "/icons/de.svg"
      }
    ]
  }
}

When i18n is configured:

The default locale pages are at the root (/about)
Non-default locale pages are prefixed (/pl/about, /de/about)
The <html> tag gets the appropriate lang attribute
hreflang link tags are added for SEO

breakpoints

Property	Type	Required	Description
`breakpoints`	`Record<string, number>`	No	Responsive breakpoint widths in pixels

Breakpoint names become keys in the style object. Default values:

{
  "breakpoints": {
    "tablet": 1024,
    "mobile": 540
  }
}

The value is the maximum viewport width (in pixels) at which the breakpoint applies. Styles are generated as @media (max-width: {value}px).

Custom breakpoints are supported:

{
  "breakpoints": {
    "desktop": 1440,
    "tablet": 1024,
    "mobile": 540
  }
}

responsiveScales

Property	Type	Required	Description
`responsiveScales`	`ResponsiveScalesConfig`	No	Auto-scaling multipliers for responsive design

When enabled, numeric CSS values for specific property types are automatically scaled at smaller breakpoints. This reduces the need to manually set tablet and mobile overrides.

Field	Type	Description
`enabled`	`boolean`	Enable or disable auto-scaling
`baseReference`	`number`	Base font size reference (typically `16`)
`fontSize`	`Record<string, number>`	Multipliers per breakpoint for font sizes
`padding`	`Record<string, number>`	Multipliers per breakpoint for padding
`margin`	`Record<string, number>`	Multipliers per breakpoint for margin
`gap`	`Record<string, number>`	Multipliers per breakpoint for gap

{
  "responsiveScales": {
    "enabled": true,
    "baseReference": 16,
    "fontSize": { "tablet": 0.8, "mobile": 0.7 },
    "padding": { "tablet": 0.75, "mobile": 0.5 },
    "margin": { "tablet": 0.7, "mobile": 0.45 },
    "gap": { "tablet": 0.65, "mobile": 0.4 }
  }
}

A multiplier of 0.75 means the value is scaled to 75% of the base value. Explicit tablet or mobile style overrides take precedence over auto-scaling.

fonts

Property	Type	Required	Description
`fonts`	`FontConfig[]`	No	Custom font definitions

Each font entry:

Field	Type	Required	Description
`path`	`string`	Yes	Path to the font file
`family`	`string`	Yes	CSS font-family name
`weight`	`number`	No	Font weight (e.g., `400`, `700`)
`fontDisplay`	`string`	No	CSS `font-display` value (`"swap"`, `"block"`, etc.)

{
  "fonts": [
    {
      "path": "/fonts/Inter-VariableFont_opsz,wght.ttf",
      "family": "Inter",
      "weight": 400,
      "fontDisplay": "swap"
    },
    {
      "path": "/fonts/FiraCode-Regular.woff2",
      "family": "Fira Code",
      "weight": 400,
      "fontDisplay": "swap"
    }
  ]
}

Fonts are rendered as @font-face declarations in the built CSS.

libraries

Property	Type	Required	Description
`libraries.js`	`LibraryConfig[]`	No	External JavaScript libraries

Each library entry:

Field	Type	Required	Description
`url`	`string`	Yes	CDN URL for the script
`name`	`string`	Yes	Library name for display
`defer`	`boolean`	No	Add `defer` attribute to script tag
`async`	`boolean`	No	Add `async` attribute to script tag

{
  "libraries": {
    "js": [
      {
        "url": "https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js",
        "name": "GSAP",
        "defer": true
      }
    ]
  }
}

csp

Property	Type	Required	Description
`csp`	`CSPConfig`	No	Content Security Policy configuration

Specifies additional allowed domains for CSP directives. These are merged with default CSP rules.

Field	Type	Description
`scriptSrc`	`string[]`	Additional script-src domains
`styleSrc`	`string[]`	Additional style-src domains
`connectSrc`	`string[]`	Additional connect-src domains
`frameSrc`	`string[]`	Additional frame-src domains
`fontSrc`	`string[]`	Additional font-src domains
`imgSrc`	`string[]`	Additional img-src domains

{
  "csp": {
    "scriptSrc": ["https://cdnjs.cloudflare.com", "https://unpkg.com"],
    "styleSrc": ["https://fonts.googleapis.com"],
    "fontSrc": ["https://fonts.gstatic.com"],
    "imgSrc": ["https://images.unsplash.com"]
  }
}

Static Build Outputs

During bun run build, the following files are auto-generated from config values:

File	Source
`robots.txt`	Generated from `siteUrl`
`sitemap.xml`	Generated from `siteUrl` and page list
Favicon `<link>` tags	From `icons.favicon` path
Apple touch icon `<link>` tag	From `icons.appleTouchIcon` path

These files are copied to the build output if they exist in the project root:

File	Purpose
`_headers`	Netlify/Cloudflare headers
`_redirects`	Netlify/Cloudflare redirects
`llms.txt`	LLM context file
`humans.txt`	Team credits
`ads.txt`	Ad network verification
`security.txt`	Security contact info
`CNAME`	GitHub Pages custom domain
`manifest.json`	PWA manifest
`site.webmanifest`	PWA web manifest
`.well-known/`	Well-known directory (copied recursively)

Next Steps

Style Properties -- how breakpoints and responsive scales affect styles
Component Props -- component types and categories
Node Types -- locale-list node requires i18n config
CMS Fields -- i18n field types for localized content