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

typescript

// 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

typescript

// 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:

typescript

// 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

typescript

// 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:

typescript

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

typescript

// 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:

typescript

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

typescript

editorComponents: editorComponents as IBlockswebComponent[];

collections

Array of collection definitions with their providers.

typescript

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

scripts (Optional)

Array of JavaScript file URLs to inject into pages.

typescript

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

styles (Optional)

Array of CSS file URLs to inject into pages.

typescript

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

Common Patterns

Organizing by Feature

typescript

// 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

typescript

// 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

typescript

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

typescript

// 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

typescript

// 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

typescript

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

typescript

// ❌ 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

typescript

// ❌ 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

typescript

// ❌ 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

Blocksweb Configuration ​

File Location ​

Basic Structure ​

Registering Components ​

Import and Register ​

Component Registration Flow ​

Registering Collections ​

With Collection Provider ​

Multiple Collections ​

Production Setup with CMS Provider ​

Development vs Production ​

Complete Configuration ​

Settings Object ​

editorComponents ​

collections ​

scripts (Optional) ​

styles (Optional) ​

Common Patterns ​

Organizing by Feature ​

Conditional Components ​

Shared Provider for All Collections ​

Importing in Your App ​

In Next.js Pages ​

In Editor ​

TypeScript Types ​

Troubleshooting ​

Component Not Appearing in Editor ​

Collections Not Working ​

TypeScript Errors ​

Next Steps ​

Key Takeaways ​

Blocksweb Configuration

File Location

Basic Structure

Registering Components

Import and Register

Component Registration Flow

Registering Collections

With Collection Provider

Multiple Collections

Production Setup with CMS Provider

Development vs Production

Complete Configuration

Settings Object

editorComponents

collections

scripts (Optional)

styles (Optional)

Common Patterns

Organizing by Feature

Conditional Components

Shared Provider for All Collections

Importing in Your App

In Next.js Pages

In Editor

TypeScript Types

Troubleshooting

Component Not Appearing in Editor

Collections Not Working

TypeScript Errors

Next Steps

Key Takeaways