BlocksWeb Configuration

The blocksweb.config.ts file is the central configuration file for your BlocksWeb project. This is where you register components, define collections, and configure your application.

File Location

Create this file in the root of your project:

your-project/
├── app/
├── components/
├── blocksweb.config.ts  ← Here
├── package.json
└── tsconfig.json

Basic Structure

// blocksweb.config.ts
import { IBlockswebComponent } from '@blocksweb/core';

// Import your components
import Hero from './components/Hero';
import FeatureSection from './components/FeatureSection';

// Register components
export const editorComponents = [
  Hero,
  FeatureSection,
];

// Export settings
export const settings = {
  editorComponents: editorComponents as IBlockswebComponent[],
  collections: [],
  scripts: [],
  styles: []
};

Registering Components

Import and Register

// blocksweb.config.ts
import Hero from './components/Hero';
import FeatureSection from './components/FeatureSection';
import BlogPost from './components/BlogPost';
import ProductGrid from './components/ProductGrid';

export const editorComponents = [
  Hero,
  FeatureSection,
  BlogPost,
  ProductGrid,
];

Important: Components must be added to the editorComponents array to appear in the visual editor.

Component Registration Flow

1. Create component file → components/Hero.tsx
2. Define component with schema → Hero.schema = {...}
3. Import in blocksweb.config.ts → import Hero from './components/Hero'
4. Add to editorComponents array → [Hero, ...]
5. Component appears in editor ✅

Registering Collections

With Collection Provider

Collections need both a definition and a provider:

// blocksweb.config.ts
import {
  CollectionDefinition,
  MemoryCollectionProvider
} from '@blocksweb/core';

// Define the collection structure
const productCollection: CollectionDefinition = {
  name: 'products',
  displayName: 'Products',
  description: 'E-commerce product catalog',
  icon: '🛍️',
  fields: [
    { name: 'name', type: 'string', label: 'Product Name', required: true },
    { name: 'price', type: 'number', label: 'Price', required: true },
    { name: 'description', type: 'richtext', label: 'Description' },
    { name: 'image', type: 'image', label: 'Product Image' },
    { name: 'inStock', type: 'boolean', label: 'In Stock' }
  ]
};

// Create provider (MemoryCollectionProvider for development)
const productProvider = new MemoryCollectionProvider({
  products: [
    {
      id: '1',
      name: 'Awesome Product',
      price: 99.99,
      description: 'The best product ever',
      image: '/product.jpg',
      inStock: true
    }
  ]
});

// Register collection with provider
export const collections = [
  {
    definition: productCollection,
    provider: productProvider
  }
];

Multiple Collections

// Define collections
const productCollection: CollectionDefinition = { /* ... */ };
const blogCollection: CollectionDefinition = { /* ... */ };
const teamCollection: CollectionDefinition = { /* ... */ };

// Create providers
const productProvider = new MemoryCollectionProvider({ products: [] });
const blogProvider = new MemoryCollectionProvider({ blog: [] });
const teamProvider = new MemoryCollectionProvider({ team: [] });

// Register all collections
export const collections = [
  { definition: productCollection, provider: productProvider },
  { definition: blogCollection, provider: blogProvider },
  { definition: teamCollection, provider: teamProvider }
];

Production Setup with CMS Provider

For production, use CMSCollectionProvider:

import {
  CollectionDefinition,
  CMSCollectionProvider
} from '@blocksweb/core';

// Define collections
const productCollection: CollectionDefinition = { /* ... */ };
const blogCollection: CollectionDefinition = { /* ... */ };

// Create CMS provider for production
const cmsProvider = new CMSCollectionProvider({
  apiUrl: process.env.BLOCKSWEB_API_URL!,
  projectId: process.env.BLOCKSWEB_PROJECT_ID!,
  apiKey: process.env.BLOCKSWEB_API_KEY
});

// Use same provider for all collections in production
export const collections = [
  { definition: productCollection, provider: cmsProvider },
  { definition: blogCollection, provider: cmsProvider }
];

Development vs Production

// blocksweb.config.ts
import {
  CollectionDefinition,
  MemoryCollectionProvider,
  CMSCollectionProvider
} from '@blocksweb/core';

const productCollection: CollectionDefinition = { /* ... */ };
const blogCollection: CollectionDefinition = { /* ... */ };

const isDevelopment = process.env.NODE_ENV === 'development';

const provider = isDevelopment
  ? new MemoryCollectionProvider({
      products: [{ id: '1', name: 'Test Product', price: 99 }],
      blog: [{ id: '1', title: 'Test Post', content: '<p>Test</p>' }]
    })
  : new CMSCollectionProvider({
      apiUrl: process.env.BLOCKSWEB_API_URL!,
      projectId: process.env.BLOCKSWEB_PROJECT_ID!
    });

export const collections = [
  { definition: productCollection, provider },
  { definition: blogCollection, provider }
];

Complete Configuration

Here's a full example with components and collections:

// blocksweb.config.ts
import {
  IBlockswebComponent,
  CollectionDefinition,
  MemoryCollectionProvider
} from '@blocksweb/core';

// ===== COMPONENTS =====
import Hero from './components/Hero';
import FeatureSection from './components/FeatureSection';
import BlogPost from './components/BlogPost';
import ProductGrid from './components/ProductGrid';

export const editorComponents = [
  Hero,
  FeatureSection,
  BlogPost,
  ProductGrid,
];

// ===== COLLECTIONS =====

// Product collection definition
const productCollection: CollectionDefinition = {
  name: 'products',
  displayName: 'Products',
  description: 'E-commerce product catalog',
  icon: '🛍️',
  fields: [
    { name: 'name', type: 'string', label: 'Product Name', required: true },
    { name: 'price', type: 'number', label: 'Price', required: true },
    { name: 'description', type: 'richtext', label: 'Description' },
    { name: 'image', type: 'image', label: 'Product Image' },
    { name: 'inStock', type: 'boolean', label: 'In Stock', default: true }
  ]
};

// Blog collection definition
const blogCollection: CollectionDefinition = {
  name: 'blog',
  displayName: 'Blog Posts',
  description: 'Articles and blog posts',
  icon: '📝',
  fields: [
    { name: 'title', type: 'string', label: 'Title', required: true },
    { name: 'slug', type: 'string', label: 'URL Slug', required: true },
    { name: 'content', type: 'richtext', label: 'Content', required: true },
    { name: 'author', type: 'string', label: 'Author', required: true },
    { name: 'publishedAt', type: 'date', label: 'Publish Date' },
    { name: 'featuredImage', type: 'image', label: 'Featured Image' }
  ]
};

// Create providers
const productProvider = new MemoryCollectionProvider({
  products: [
    {
      id: '1',
      name: 'Laptop',
      price: 999,
      description: '<p>High-performance laptop</p>',
      image: '/laptop.jpg',
      inStock: true
    },
    {
      id: '2',
      name: 'Headphones',
      price: 199,
      description: '<p>Noise-cancelling headphones</p>',
      image: '/headphones.jpg',
      inStock: true
    }
  ]
});

const blogProvider = new MemoryCollectionProvider({
  blog: [
    {
      id: '1',
      title: 'Getting Started with BlocksWeb',
      slug: 'getting-started',
      content: '<p>Welcome to BlocksWeb...</p>',
      author: 'John Doe',
      publishedAt: '2024-01-15',
      featuredImage: '/blog/getting-started.jpg'
    }
  ]
});

// Register collections
export const collections = [
  { definition: productCollection, provider: productProvider },
  { definition: blogCollection, provider: blogProvider }
];

// ===== SETTINGS =====
export const settings = {
  editorComponents: editorComponents as IBlockswebComponent[],
  collections,
  scripts: [],
  styles: []
};

Settings Object

editorComponents

Array of registered components that appear in the visual editor.

editorComponents: editorComponents as IBlockswebComponent[]

collections

Array of collection definitions with their providers.

collections: [
  { definition: productCollection, provider: productProvider }
]

scripts (Optional)

Array of JavaScript file URLs to inject into pages.

scripts: [
  'https://cdn.example.com/analytics.js',
  '/custom-script.js'
]

styles (Optional)

Array of CSS file URLs to inject into pages.

styles: [
  '/_next/static/css/app/layout.css',
  '/custom-styles.css'
]

Common Patterns

Organizing by Feature

// blocksweb.config.ts
import { heroComponents } from './components/hero';
import { marketingComponents } from './components/marketing';
import { ecommerceComponents } from './components/ecommerce';

export const editorComponents = [
  ...heroComponents,
  ...marketingComponents,
  ...ecommerceComponents,
];

Conditional Components

// blocksweb.config.ts
import Hero from './components/Hero';
import DebugPanel from './components/Debug';

const baseComponents = [Hero];
const devComponents = process.env.NODE_ENV === 'development'
  ? [DebugPanel]
  : [];

export const editorComponents = [
  ...baseComponents,
  ...devComponents
];

Shared Provider for All Collections

const provider = new CMSCollectionProvider({
  apiUrl: process.env.BLOCKSWEB_API_URL!,
  projectId: process.env.BLOCKSWEB_PROJECT_ID!
});

export const collections = [
  { definition: productCollection, provider },
  { definition: blogCollection, provider },
  { definition: teamCollection, provider },
  // All use the same CMS provider
];

Importing in Your App

In Next.js Pages

// app/[[...slug]]/page.tsx
import { settings } from '@/blocksweb.config';
import { BlockswebProvider } from '@blocksweb/core/client';

export default function Page() {
  return (
    <BlockswebProvider settings={settings}>
      {/* Your app */}
    </BlockswebProvider>
  );
}

In Editor

// app/admin/cms/[[...slug]]/page.tsx
import { settings } from '@/blocksweb.config';
import { Editor } from '@blocksweb/core/editor';

export default function EditorPage() {
  return <Editor settings={settings} />;
}

TypeScript Types

import type {
  IBlockswebComponent,
  CollectionDefinition,
  BlockswebSettings
} from '@blocksweb/core';

export const editorComponents: IBlockswebComponent[] = [
  /* components */
];

export const collections: Array<{
  definition: CollectionDefinition;
  provider: CollectionProvider;
}> = [
  /* collections */
];

export const settings: BlockswebSettings = {
  editorComponents,
  collections,
  scripts: [],
  styles: []
};

Troubleshooting

Component Not Appearing in Editor

// ❌ Problem: Component not registered
// components/Hero.tsx exists but not imported

// ✅ Solution: Import and register
import Hero from './components/Hero';

export const editorComponents = [
  Hero  // Now it appears in editor
];

Collections Not Working

// ❌ Problem: No provider specified
export const collections = [
  { definition: productCollection }  // Missing provider!
];

// ✅ Solution: Add provider
const provider = new MemoryCollectionProvider({ products: [] });

export const collections = [
  { definition: productCollection, provider }
];

TypeScript Errors

// ❌ Problem: Missing type cast
export const settings = {
  editorComponents,  // Type error!
};

// ✅ Solution: Cast to correct type
export const settings = {
  editorComponents: editorComponents as IBlockswebComponent[],
};

Next Steps

• Creating Components - Build components to register
• Defining Collections - Create collection structures
• Collection Providers - Setup data sources
• Project Structure - Understand file organization

Key Takeaways

✅ blocksweb.config.ts is the central configuration file ✅ Register components in editorComponents array ✅ Collections need both definition and provider ✅ Use MemoryCollectionProvider for development ✅ Use CMSCollectionProvider for production ✅ Import settings in your app and editor pages ✅ Components must be registered to appear in the visual editor