BlocksWeb Developer Docs

Appearance

Common Issues and Solutions ​

This guide covers the most common issues developers encounter when working with BlocksWeb and how to resolve them.

Installation & Setup Issues ​

"Cannot find module '@blocksweb/core'" ​

Problem: TypeScript or Node cannot find the BlocksWeb package.

Solutions:

bash
# 1. Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# 2. Clear Next.js cache
rm -rf .next

# 3. Verify package is installed
npm list @blocksweb/core

# 4. Check package.json
cat package.json | grep blocksweb

If the package isn't listed, install it:

bash
npm install @blocksweb/core@latest

"Invalid API Key" Error ​

Problem: BlocksWeb cannot authenticate with the API.

Checklist:

  1. Check .env.local exists in project root
  2. Verify variable names are correct:
    bash
    BLOCKSWEB_API_KEY=bw_live_...
BLOCKSWEB_WORKSPACE_ID=ws_...
  3. No extra spaces around the = sign
  4. Restart dev server after adding variables:
    bash
    # Stop server (Ctrl+C), then:
npm run dev
  5. Verify API key is valid in BlocksWeb Dashboard

Environment Variables Not Loading ​

Problem: Environment variables are undefined in your code.

Common causes:

1. Server vs Client Variables

typescript
// ❌ Won't work - server-only variable on client
'use client';
const apiKey = process.env.BLOCKSWEB_API_KEY; // undefined

// ✅ Works - use NEXT_PUBLIC_ prefix for client
const siteUrl = process.env.NEXT_PUBLIC_SITE_URL;

2. File location

.env.local must be in project root:

my-project/
├── .env.local          ✅ Correct
├── app/
│   └── .env.local      ❌ Wrong location
└── package.json

3. Git-ignored

Make sure .env.local is in .gitignore:

gitignore
# Environment files
.env.local
.env.*.local

Component Issues ​

Component Not Appearing in Editor ​

Problem: Your component doesn't show up in the "Add Block" menu.

Checklist:

  1. Component is exported as default:

    typescript
    export default MyComponent; // ✅
export const MyComponent = ...; // ❌

  2. Schema is attached:

    typescript
    MyComponent.schema = {
  displayName: 'My Component',
  options: []
}; // ✅

  3. Component is registered:

    typescript
    // blocksweb.config.ts
import MyComponent from './components/MyComponent';

export const editorComponents = [
  MyComponent, // ✅
];

  4. Browser cache cleared: Hard refresh (Ctrl+Shift+R / Cmd+Shift+R)

  5. No TypeScript errors: Run npm run type-check

"Cannot read property 'schema' of undefined" ​

Problem: Component schema is not properly attached.

Solution:

Make sure schema is attached before export:

typescript
const MyComponent: IBlockswebComponent = () => {
  return <div>Content</div>;
};

// ✅ Attach schema BEFORE export
MyComponent.schema = {
  displayName: 'My Component',
  options: []
};

export default MyComponent;

Don't do this:

typescript
// ❌ Wrong - exporting before attaching schema
export default MyComponent;

MyComponent.schema = {
  displayName: 'My Component',
  options: []
};

Props Not Updating in Real-Time ​

Problem: Changes in the editor don't reflect in the component.

Checklist:

  1. Prop names match schema:

    typescript
    // Schema
{ type: 'text', name: 'title', ... }

// Component props
const MyComponent = ({ title }) => { // ✅ Names match
  return <h1>{title}</h1>;
};

  2. Using props, not hardcoded values:

    typescript
    // ✅ Good - uses prop
<h1>{title}</h1>

// ❌ Bad - hardcoded
<h1>Hardcoded Title</h1>

  3. Component is not memoized incorrectly:

    typescript
    // ❌ Bad - will not re-render on prop changes
const MyComponent = React.memo(({ title }) => {
  return <h1>{title}</h1>;
}, () => true); // Always returns true, never re-renders

// ✅ Good - proper memoization
const MyComponent = React.memo(({ title }) => {
  return <h1>{title}</h1>;
});

TypeScript Errors ​

"Type 'IBlockswebComponent' is not assignable to type 'FunctionComponent'" ​

Problem: Type mismatch between BlocksWeb component and React component.

Solution:

Use the IBlockswebComponent type correctly:

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

// ✅ Correct
const MyComponent: IBlockswebComponent<MyProps> = (props) => {
  return <div>...</div>;
};

// ❌ Wrong
const MyComponent: React.FC<MyProps> = (props) => {
  return <div>...</div>;
};

"Property 'schema' does not exist on type..." ​

Problem: TypeScript doesn't recognize the schema property.

Solution:

Make sure you're using IBlockswebComponent type:

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

const MyComponent: IBlockswebComponent = () => { // ✅ Has schema property
  return <div>...</div>;
};

MyComponent.schema = { // Now TypeScript is happy
  displayName: 'My Component',
  options: []
};

Data Fetching Issues ​

"Cannot read property 'data' of undefined" ​

Problem: Hook result is undefined.

Solution:

Always check loading and error states:

typescript
const { data, isLoading, error } = useCollection('products');

if (isLoading) return <div>Loading...</div>;
if (error) return <div>Error: {error.message}</div>;
if (!data) return null;

return <div>{data.map(...)}</div>;

Infinite Re-renders ​

Problem: Component keeps re-rendering infinitely.

Common causes:

1. Creating objects in render:

typescript
// ❌ Bad - creates new object every render
const { data } = useCollection('products', {
  where: { inStock: true }  // New object every time
});

// ✅ Good - memoize the query
const query = useMemo(() => ({
  where: { inStock: true }
}), []);

const { data } = useCollection('products', query);

2. Missing dependencies:

typescript
// ❌ Bad
useEffect(() => {
  fetchData();
}, []); // Missing fetchData dependency

// ✅ Good
const fetchData = useCallback(() => {
  // Fetch logic
}, []);

useEffect(() => {
  fetchData();
}, [fetchData]);

"Failed to fetch" or Network Errors ​

Problem: Cannot connect to BlocksWeb API.

Checklist:

  1. Check internet connection

  2. Verify API URL:

    bash
    # Default (cloud)
BLOCKSWEB_API_URL=https://cloud.blocksweb.nl

# Custom (self-hosted)
BLOCKSWEB_API_URL=https://api.yoursite.com

  3. Check CORS settings (if self-hosting)

  4. Verify API key is valid in BlocksWeb dashboard

  5. Check API status: Visit status.blocksweb.nl

Build & Deployment Issues ​

Build Fails with "Module parse failed" ​

Problem: Next.js cannot parse a file.

Common causes:

1. Missing file extension:

typescript
// ❌ Bad
import Hero from './components/Hero'; // Will look for .js/.jsx

// ✅ Good
import Hero from './components/Hero.tsx';

2. Invalid TypeScript:

bash
# Run type check to find errors
npm run type-check

3. Missing dependencies:

bash
# Reinstall dependencies
npm install

"Cannot find module" in Production ​

Problem: Build works locally but fails in production.

Solutions:

1. Check file paths are correct:

typescript
// ❌ Bad - case-sensitive on Linux
import Hero from './Components/Hero'; // Capital C

// ✅ Good - match actual filename
import Hero from './components/Hero'; // Lowercase c

2. Verify dependencies are in dependencies, not devDependencies:

json
{
  "dependencies": {
    "@blocksweb/core": "^2.0.0", // ✅
    "react": "^18.0.0"
  },
  "devDependencies": {
    "@types/react": "^18.0.0" // ✅ Types can be in devDependencies
  }
}

Out of Memory During Build ​

Problem: Build fails with "JavaScript heap out of memory".

Solutions:

1. Increase Node memory:

json
// package.json
{
  "scripts": {
    "build": "NODE_OPTIONS='--max-old-space-size=4096' next build"
  }
}

2. Optimize bundle size:

javascript
// next.config.js
module.exports = {
  experimental: {
    optimizeCss: true,
  },
  webpack: (config) => {
    config.optimization.splitChunks = {
      chunks: 'all',
    };
    return config;
  },
};

Editor Issues ​

Editor Not Loading ​

Problem: Editor shows blank screen or loading forever.

Checklist:

  1. Check browser console for errors (F12)

  2. Verify API key is correct

  3. Clear browser cache:

    • Chrome: Ctrl+Shift+Delete
    • Firefox: Ctrl+Shift+Delete
    • Safari: Cmd+Option+E

  4. Try incognito/private mode

  5. Check browser compatibility:

    • Chrome 90+
    • Firefox 88+
    • Safari 14+
    • Edge 90+

Changes Not Saving ​

Problem: Edits in the editor don't persist.

Solutions:

  1. Check auto-save status in editor UI

  2. Manually save: Use Cmd/Ctrl+S or click "Save" button

  3. Check network tab (F12 → Network) for failed requests

  4. Verify API key has write permissions

  5. Check workspace plan hasn't exceeded limits

Performance Issues ​

Slow Page Load ​

Problem: Pages take too long to load.

Solutions:

1. Enable ISR (Incremental Static Regeneration):

typescript
// app/[[...path]]/page.tsx
export const revalidate = 60; // Revalidate every 60 seconds

2. Optimize images:

typescript
import { Image } from '@blocksweb/core/client';

// Images are automatically optimized
<Image propName="hero" asset={heroImage} alt="Hero" />

3. Use dynamic imports:

typescript
import dynamic from 'next/dynamic';

const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
  loading: () => <div>Loading...</div>,
});

4. Enable caching:

typescript
// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'Cache-Control',
            value: 's-maxage=60, stale-while-revalidate',
          },
        ],
      },
    ];
  },
};

Large Bundle Size ​

Problem: JavaScript bundle is too large.

Solutions:

1. Analyze bundle:

bash
npm install -D @next/bundle-analyzer
javascript
// next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});

module.exports = withBundleAnalyzer({});
bash
ANALYZE=true npm run build

2. Use tree shaking:

typescript
// ✅ Good - imports only what you need
import { usePage } from '@blocksweb/core/client';

// ❌ Bad - imports everything
import * as Blocksweb from '@blocksweb/core/client';

3. Lazy load components:

typescript
const ProductGrid = dynamic(() => import('@/components/ProductGrid'));

Getting More Help ​

If you're still stuck:

  1. Check Debug Mode: Enable debug logging:

    typescript
    // blocksweb.config.ts
export const settings = {
  debug: true, // Enable debug logs
  // ...
};

  2. Search GitHub Issues: github.com/blockswebnl/blocksweb/issues

  3. Ask on Discord: discord.gg/blocksweb

  4. Contact Support: support@blocksweb.nl

Next Steps ​