Configuration Reference

Complete reference for configuring BlocksWeb via blocksweb.config.ts.

Basic Configuration

The minimum required configuration:

typescript

import { IBlockswebComponent } from '@blocksweb/core';

export const editorComponents: IBlockswebComponent[] = [];

export const settings = {
  editorComponents,
};

Full Configuration

Here's a complete example with all available options:

typescript

import { IBlockswebComponent } from '@blocksweb/core';
import Hero from './components/Hero';
import FeatureCard from './components/FeatureCard';

export const editorComponents: IBlockswebComponent[] = [
  Hero,
  FeatureCard,
];

export const collections = [
  {
    name: 'products',
    displayName: 'Products',
    fields: [
      { name: 'name', type: 'string', required: true },
      { name: 'price', type: 'number', required: true },
      { name: 'image', type: 'image' },
      { name: 'description', type: 'richtext' },
    ],
  },
];

export const settings = {
  // Components
  editorComponents,

  // Collections
  collections,

  // Scripts (loaded in editor)
  scripts: [
    'https://cdn.tailwindcss.com',
    '/custom-script.js',
  ],

  // Stylesheets (loaded in editor)
  styles: [
    '/custom-styles.css',
    'https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap',
  ],

  // API Configuration
  apiUrl: 'https://cloud.blocksweb.nl',
  apiVersion: 'v1',

  // Feature Flags
  features: {
    analytics: true,
    abTesting: true,
    translations: true,
    versionHistory: true,
  },

  // Localization
  locales: ['en', 'nl', 'de', 'fr'],
  defaultLocale: 'en',

  // Caching
  cache: {
    enabled: true,
    ttl: 3600, // seconds
    strategy: 'stale-while-revalidate',
  },

  // Debug mode
  debug: false,

  // Custom theme
  theme: {
    primaryColor: '#1F3A66',
    accentColor: '#F95A25',
  },
};

Configuration Options

editorComponents

Type: IBlockswebComponent[]

Required: Yes

Array of components available in the visual editor.

typescript

import Hero from './components/Hero';
import FeatureCard from './components/FeatureCard';

export const editorComponents = [
  Hero,
  FeatureCard,
];

collections

Type: Collection[]

Required: No

Define structured data collections (products, blog posts, etc.).

typescript

export const collections = [
  {
    name: 'products',
    displayName: 'Products',
    description: 'Product catalog',
    fields: [
      {
        name: 'name',
        type: 'string',
        label: 'Product Name',
        required: true,
      },
      {
        name: 'price',
        type: 'number',
        label: 'Price',
        required: true,
      },
      {
        name: 'inStock',
        type: 'boolean',
        label: 'In Stock',
        default: true,
      },
    ],
    provider: 'cms', // or custom provider
  },
];

Collection Field Types:

string - Text field
number - Numeric field
boolean - Checkbox
date - Date picker
image - Image upload
richtext - Rich text editor
reference - Reference to another collection

scripts

Type: string[]

Required: No

JavaScript files to load in the editor (for styling frameworks, etc.).

typescript

export const settings = {
  scripts: [
    'https://cdn.tailwindcss.com',
    '/analytics.js',
  ],
};

TIP

Scripts are only loaded in the editor, not on your production site. Add production scripts to your layout.

styles

Type: string[]

Required: No

CSS files to load in the editor.

typescript

export const settings = {
  styles: [
    '/custom-styles.css',
    'https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap',
  ],
};

apiUrl

Type: string

Default: 'https://cloud.blocksweb.nl'

Required: No

URL of the BlocksWeb API. Override for self-hosting.

typescript

export const settings = {
  apiUrl: 'https://api.mysite.com',
};

Can also be set via environment variable:

bash

BLOCKSWEB_API_URL=https://api.mysite.com

apiVersion

Type: string

Default: 'v1'

Required: No

API version to use.

typescript

export const settings = {
  apiVersion: 'v2',
};

features

Type: object

Required: No

Enable/disable BlocksWeb features.

typescript

export const settings = {
  features: {
    analytics: true,       // Page analytics
    abTesting: true,       // A/B testing
    translations: true,    // Multi-language support
    versionHistory: true,  // Page version history
    comments: false,       // Editor comments
    workflows: false,      // Custom workflows
  },
};

locales

Type: string[]

Default: ['en']

Required: No

Available languages for content translation.

typescript

export const settings = {
  locales: ['en', 'nl', 'de', 'fr', 'es'],
  defaultLocale: 'en',
};

defaultLocale

Type: string

Default: 'en'

Required: No

Default language for new content.

typescript

export const settings = {
  defaultLocale: 'en',
};

cache

Type: object

Required: No

Configure caching behavior.

typescript

export const settings = {
  cache: {
    enabled: true,
    ttl: 3600,                           // Time to live (seconds)
    strategy: 'stale-while-revalidate',  // or 'cache-first'
    invalidateOn: ['publish', 'update'], // When to invalidate
  },
};

Strategies:

'cache-first' - Serve from cache, fetch in background
'stale-while-revalidate' - Serve stale data while revalidating
'network-first' - Always fetch fresh data
'network-only' - Never cache

debug

Type: boolean

Default: false

Required: No

Enable debug logging.

typescript

export const settings = {
  debug: true, // Log API calls, component renders, etc.
};

Or via environment variable:

bash

BLOCKSWEB_DEBUG=true

theme

Type: object

Required: No

Customize editor theme colors.

typescript

export const settings = {
  theme: {
    primaryColor: '#1F3A66',
    accentColor: '#F95A25',
    backgroundColor: '#ffffff',
    textColor: '#000000',
    borderRadius: '8px',
  },
};

customFields

Type: object

Required: No

Add custom fields to pages.

typescript

export const settings = {
  customFields: {
    page: [
      {
        name: 'author',
        type: 'string',
        label: 'Page Author',
      },
      {
        name: 'category',
        type: 'select',
        label: 'Category',
        options: [
          { label: 'Blog', value: 'blog' },
          { label: 'Product', value: 'product' },
        ],
      },
    ],
  },
};

seo

Type: object

Required: No

Default SEO settings.

typescript

export const settings = {
  seo: {
    defaultTitle: 'My Website',
    titleTemplate: '%s | My Website',
    defaultDescription: 'Welcome to my website',
    defaultImage: '/og-image.jpg',
    twitterHandle: '@mywebsite',
  },
};

assetStorage

Type: object

Required: No

Configure asset storage.

typescript

export const settings = {
  assetStorage: {
    provider: 'vercel-blob', // or 's3', 'cloudflare-r2'
    maxFileSize: 10 * 1024 * 1024, // 10 MB
    allowedTypes: ['image/jpeg', 'image/png', 'image/webp'],
    transformations: {
      quality: 85,
      format: 'webp',
    },
  },
};

webhooks

Type: object[]

Required: No

Configure webhooks for events.

typescript

export const settings = {
  webhooks: [
    {
      event: 'page.published',
      url: 'https://myapi.com/webhook',
      secret: process.env.WEBHOOK_SECRET,
    },
    {
      event: 'page.updated',
      url: 'https://myapi.com/webhook',
    },
  ],
};

Available Events:

page.created
page.updated
page.published
page.deleted
collection.record.created
collection.record.updated
collection.record.deleted

Environment Variables

BlocksWeb uses these environment variables:

Required

bash

# API Authentication
BLOCKSWEB_API_KEY=bw_live_...
BLOCKSWEB_WORKSPACE_ID=ws_...

Optional

bash

# API URL (for self-hosting)
BLOCKSWEB_API_URL=https://cloud.blocksweb.nl

# Feature Flags
BLOCKSWEB_ENABLE_ANALYTICS=true
BLOCKSWEB_ENABLE_AB_TESTING=true
BLOCKSWEB_DEBUG=false

# Caching
BLOCKSWEB_CACHE_ENABLED=true
BLOCKSWEB_CACHE_TTL=3600

# Asset Storage
BLOCKSWEB_STORAGE_PROVIDER=vercel-blob
BLOCKSWEB_STORAGE_ACCESS_KEY=...
BLOCKSWEB_STORAGE_SECRET_KEY=...

TypeScript Types

Import types for full type safety:

typescript

import type {
  BlockswebSettings,
  Collection,
  CollectionField,
  CacheStrategy,
  AssetStorageProvider,
} from '@blocksweb/core/types';

export const settings: BlockswebSettings = {
  // Fully typed configuration
};

Advanced Configuration

Custom Provider

Create a custom data provider:

typescript

import { CollectionProvider } from '@blocksweb/core';

class CustomProvider implements CollectionProvider {
  async findMany(collection: string, query: Query) {
    // Custom implementation
  }

  async findOne(collection: string, id: string) {
    // Custom implementation
  }

  async create(collection: string, data: any) {
    // Custom implementation
  }

  async update(collection: string, id: string, data: any) {
    // Custom implementation
  }

  async delete(collection: string, id: string) {
    // Custom implementation
  }
}

export const settings = {
  providers: {
    products: new CustomProvider(),
  },
};

Dynamic Configuration

Load configuration dynamically:

typescript

// blocksweb.config.ts
const isDev = process.env.NODE_ENV === 'development';

export const settings = {
  debug: isDev,
  apiUrl: isDev
    ? 'http://localhost:3001'
    : 'https://cloud.blocksweb.nl',
  features: {
    analytics: !isDev,
  },
};

Per-Environment Config

typescript

// lib/blocksweb.config.ts
const baseConfig = {
  editorComponents: [...],
};

const devConfig = {
  ...baseConfig,
  debug: true,
  apiUrl: 'http://localhost:3001',
};

const prodConfig = {
  ...baseConfig,
  debug: false,
  cache: {
    enabled: true,
    ttl: 3600,
  },
};

export const settings =
  process.env.NODE_ENV === 'production' ? prodConfig : devConfig;

Validation

BlocksWeb validates your configuration on startup. Common validation errors:

Missing required fields:

Error: editorComponents is required in settings

Invalid types:

Error: apiUrl must be a string

Duplicate component names:

Error: Duplicate component displayName: "Hero"

Enable strict mode for more validation:

typescript

export const settings = {
  strict: true, // Throw errors instead of warnings
};

Next Steps

Client Hooks - Use data fetching hooks
Creating Components - Build BlocksWeb components
Defining Collections - Create collection structures

Configuration Reference ​

Basic Configuration ​

Full Configuration ​

Configuration Options ​

editorComponents ​

collections ​

scripts ​

styles ​

apiUrl ​

apiVersion ​

features ​

locales ​

defaultLocale ​

cache ​

debug ​

theme ​

customFields ​

seo ​

assetStorage ​

webhooks ​

Environment Variables ​

Required ​

Optional ​

TypeScript Types ​

Advanced Configuration ​

Custom Provider ​

Dynamic Configuration ​

Per-Environment Config ​

Validation ​

Next Steps ​

Configuration Reference

Basic Configuration

Full Configuration

Configuration Options

editorComponents

collections

scripts

styles

apiUrl

apiVersion

features

locales

defaultLocale

cache

debug

theme

customFields

seo

assetStorage

webhooks

Environment Variables

Required

Optional

TypeScript Types

Advanced Configuration

Custom Provider

Dynamic Configuration

Per-Environment Config

Validation

Next Steps