BlocksWeb Developer Docs

Appearance

Installation ​

This guide covers detailed installation instructions for BlocksWeb, including different setup methods and configuration options.

System Requirements ​

Before installing BlocksWeb, ensure your system meets these requirements:

  • Node.js: Version 18.0.0 or higher
  • npm: Version 9.0.0 or higher (or yarn/pnpm equivalent)
  • Operating System: Windows, macOS, or Linux
  • Browser: Modern browser (Chrome, Firefox, Safari, Edge)

Installation Methods ​

There are three ways to install BlocksWeb:

  1. CLI Tool (Recommended for new projects)
  2. Manual Installation (For existing projects)
  3. Clone Example (For learning)

The easiest way to get started is with the BlocksWeb CLI:

bash
npx create-blocksweb-app@latest

CLI Options ​

The CLI will ask you several questions:

✔ What is your project named? … my-project
✔ Which template would you like to use?
  › App Router (Recommended)
  › Pages Router
  › E-commerce Starter
  › Marketing Site
✔ Would you like to use TypeScript? … Yes
✔ Would you like to install dependencies now? … Yes

What Gets Installed ​

The CLI creates a new project with:

  • ✅ Next.js configured for BlocksWeb
  • ✅ TypeScript setup
  • ✅ @blocksweb/core package installed
  • ✅ Basic component examples
  • ✅ blocksweb.config.ts pre-configured
  • ✅ Tailwind CSS (optional)
  • ✅ ESLint and Prettier

Method 2: Manual Installation ​

If you have an existing Next.js project, you can add BlocksWeb manually.

Step 1: Install the Package ​

bash
npm install @blocksweb/core@latest

Or with yarn:

bash
yarn add @blocksweb/core@latest

Or with pnpm:

bash
pnpm add @blocksweb/core@latest

Step 2: Install Peer Dependencies ​

BlocksWeb requires React 18+ and Next.js 11+:

bash
npm install react@18 react-dom@18 next@15

Step 3: Create Configuration File ​

Create blocksweb.config.ts in your project root:

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

export const editorComponents: IBlockswebComponent[] = [];

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

Step 4: Set Up Next.js (App Router) ​

If using App Router, create app/[[...path]]/page.tsx:

typescript
import { BlockswebProvider, Canvas } from '@blocksweb/core/client';
import { settings } from '@/blocksweb.config';

export default function Page({ params }: { params: { path?: string[] } }) {
  const path = params.path ? '/' + params.path.join('/') : '/';

  return (
    <BlockswebProvider settings={settings}>
      <Canvas path={path} />
    </BlockswebProvider>
  );
}

Step 5: Set Up Next.js (Pages Router) ​

If using Pages Router, create pages/[[...path]].tsx:

typescript
import { BlockswebProvider, Canvas } from '@blocksweb/core/client';
import { settings } from '@/blocksweb.config';
import { GetServerSideProps } from 'next';

export default function Page({ path }: { path: string }) {
  return (
    <BlockswebProvider settings={settings}>
      <Canvas path={path} />
    </BlockswebProvider>
  );
}

export const getServerSideProps: GetServerSideProps = async (context) => {
  const path = context.params?.path
    ? '/' + (context.params.path as string[]).join('/')
    : '/';

  return {
    props: { path },
  };
};

Step 6: Add Environment Variables ​

Create .env.local:

bash
BLOCKSWEB_API_KEY=your_api_key_here
BLOCKSWEB_WORKSPACE_ID=your_workspace_id_here

Step 7: Import Styles ​

In your root layout (app/layout.tsx or pages/_app.tsx), import BlocksWeb styles:

typescript
import '@blocksweb/core/style.css';

Method 3: Clone Example Project ​

Clone one of our example projects to get started:

bash
# Marketing site example
git clone https://github.com/blockswebnl/blocksweb-example-marketing.git
cd blocksweb-example-marketing
npm install

# E-commerce example
git clone https://github.com/blockswebnl/blocksweb-example-ecommerce.git
cd blocksweb-example-ecommerce
npm install

# Blog example
git clone https://github.com/blockswebnl/blocksweb-example-blog.git
cd blocksweb-example-blog
npm install

Getting Your API Key ​

BlocksWeb requires an API key to function. Here's how to get one:

1. Create an Account ​

Go to https://cloud.blocksweb.nl and sign up for a free account.

2. Create a Workspace ​

After signing in:

  1. Click "Create New Workspace"
  2. Enter a workspace name (e.g., "My Website")
  3. Choose your plan (Free tier available)

3. Get Your Credentials ​

In the workspace dashboard:

  1. Go to Settings → API Keys
  2. Copy your API Key
  3. Copy your Workspace ID

4. Add to Environment Variables ​

Add these to your .env.local file:

bash
BLOCKSWEB_API_KEY=bw_live_abc123...
BLOCKSWEB_WORKSPACE_ID=ws_123456...

Important

  • Keep your API key secret
  • Never commit .env.local to version control
  • Add .env.local to your .gitignore file

Verifying Installation ​

After installation, verify everything is working:

1. Start Development Server ​

bash
npm run dev

2. Open Browser ​

Navigate to http://localhost:3000

3. Check for Sign-In Page ​

You should see the BlocksWeb sign-in page. If you see an error, check:

  • API key is correct in .env.local
  • .env.local is in the project root
  • You restarted the dev server after adding environment variables

4. Sign In ​

Use your BlocksWeb account credentials to sign in. You should see the empty editor.

TypeScript Configuration ​

For the best experience, update your tsconfig.json:

json
{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Optional: Install Tailwind CSS ​

BlocksWeb works great with Tailwind CSS for styling:

bash
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Configure tailwind.config.js:

javascript
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './app/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Add Tailwind directives to your CSS:

css
/* app/globals.css or styles/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

Next Steps ​

Now that BlocksWeb is installed, you're ready to:

  1. Create Your First Component - Build a simple component
  2. Understand Project Structure - Learn the file organization
  3. Explore Components & Schema - Deep dive into architecture

Troubleshooting ​

Module Not Found Error ​

If you see Cannot find module '@blocksweb/core':

bash
# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

API Key Error ​

If you see "Invalid API key":

  • Check the key is correct in .env.local
  • Ensure there are no extra spaces
  • Verify the workspace ID matches

TypeScript Errors ​

If you see TypeScript errors:

bash
# Install type definitions
npm install --save-dev @types/react @types/node

Next.js Version Compatibility ​

BlocksWeb supports Next.js 11-15. If you're using an older version:

bash
npm install next@latest

Upgrade Guide ​

To upgrade BlocksWeb to the latest version:

bash
npm install @blocksweb/core@latest

Check the changelog for breaking changes.

Need Help? ​

If you encounter issues: