BlocksWeb Developer Docs

Appearance

Quick Start ​

Get up and running with BlocksWeb in under 5 minutes. This guide will help you create a new BlocksWeb project, create your first component, and see it in the visual editor.

Prerequisites ​

Before you begin, make sure you have:

  • Node.js 18+ installed (Download Node.js)
  • Basic knowledge of React and TypeScript
  • A code editor (VS Code recommended)

Step 1: Create a New Project ​

Open your terminal and run the following command:

bash
npx create-blocksweb-app@latest my-blocksweb-project

This will prompt you to enter a project name. The CLI will create a new Next.js project with BlocksWeb pre-configured.

TIP

The setup wizard will ask you to choose between App Router and Pages Router. Choose App Router if you're starting fresh (recommended for new projects).

Step 2: Install Dependencies ​

Navigate to your new project and install dependencies:

bash
cd my-blocksweb-project
npm install

This may take a few minutes as it installs all necessary packages.

Step 3: Get Your API Key ​

BlocksWeb requires an API key to connect to the cloud service:

  1. Go to https://cloud.blocksweb.nl
  2. Sign up or sign in with your account
  3. Create a new workspace
  4. Copy your API key from the workspace settings

Step 4: Configure Environment Variables ​

Create a .env.local file in your project root:

bash
# .env.local
BLOCKSWEB_API_KEY=your_api_key_here
BLOCKSWEB_WORKSPACE_ID=your_workspace_id_here

WARNING

Never commit your .env.local file to version control. Add it to .gitignore.

Step 5: Start the Development Server ​

Start your development server:

bash
npm run dev

Open http://localhost:3000 in your browser. You should see the BlocksWeb sign-in page.

Step 6: Sign In to the Editor ​

Click "Sign In" and use the same credentials from Step 3. After signing in, you'll see the BlocksWeb editor interface with an empty page.

Step 7: Create Your First Component ​

Create a new file components/Hero.tsx:

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

type HeroProps = {
  title: string;
  subtitle: string;
  buttonText: string;
  buttonUrl: string;
};

const Hero: IBlockswebComponent<HeroProps> = ({
  title,
  subtitle,
  buttonText,
  buttonUrl
}) => {
  return (
    <section className="hero">
      <div className="container mx-auto px-4 py-16 text-center">
        <h1 className="text-5xl font-bold mb-4">{title}</h1>
        <p className="text-xl mb-8">{subtitle}</p>
        <a
          href={buttonUrl}
          className="bg-blue-600 text-white px-8 py-3 rounded-lg hover:bg-blue-700"
        >
          {buttonText}
        </a>
      </div>
    </section>
  );
};

Hero.schema = {
  displayName: 'Hero Section',
  category: 'Marketing',
  options: [
    {
      type: 'text',
      name: 'title',
      label: 'Title',
      default: 'Welcome to Our Website'
    },
    {
      type: 'text',
      name: 'subtitle',
      label: 'Subtitle',
      default: 'Build something amazing with BlocksWeb'
    },
    {
      type: 'text',
      name: 'buttonText',
      label: 'Button Text',
      default: 'Get Started'
    },
    {
      type: 'text',
      name: 'buttonUrl',
      label: 'Button URL',
      default: '/signup'
    }
  ]
};

export default Hero;

Step 8: Register Your Component ​

Open blocksweb.config.ts and register your new component:

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

export const editorComponents: IBlockswebComponent[] = [
  Hero,
  // Add more components here
];

export const settings = {
  editorComponents,
  scripts: ['https://cdn.tailwindcss.com'], // For styling
};

Step 9: Use Your Component ​

  1. Go back to your browser at http://localhost:3000
  2. Click the "+ Add Block" button
  3. Find "Hero Section" in the component list
  4. Click to add it to the page
  5. You should see your hero component appear!

Step 10: Edit in the Visual Editor ​

Now the magic happens:

  1. Click on your hero component in the canvas
  2. The property panel opens on the right
  3. Change the title to "My Awesome Website"
  4. Change the subtitle to "Let's build something great"
  5. Watch it update in real-time!

Next Steps ​

Congratulations! You've created your first BlocksWeb project and component. Here's what to explore next:

Learn Core Concepts ​

Build More Components ​

Add Collections ​

Deploy to Production ​

Troubleshooting ​

API Key Not Working ​

Make sure your .env.local file is in the project root and the variable names are correct:

BLOCKSWEB_API_KEY=...
BLOCKSWEB_WORKSPACE_ID=...

Restart the dev server after adding environment variables.

Component Not Appearing ​

  1. Check that the component is exported as default
  2. Verify it's registered in blocksweb.config.ts
  3. Make sure it has a schema property
  4. Refresh your browser

TypeScript Errors ​

If you see TypeScript errors, run:

bash
npm run type-check

This will show you exactly what needs to be fixed.

Get Help ​

Now you're ready to build amazing things with BlocksWeb!