@verto.js/blocks

Installable website block components for Verto.js - inspired by shadcn/ui's approach of copying components directly into your project for full customization.

Installation

npm install -D @verto.js/blocks
# or
pnpm add -D @verto.js/blocks
# or
yarn add -D @verto.js/blocks

Quick Start

1. Initialize your project

Set up Verto blocks in your project:

npx verto-blocks init

This will:

• Create a verto.config.json file
• Set up your blocks directory (default: ./src/blocks)
• Install utility functions (optional)

2. Add blocks to your project

Browse and install blocks interactively:

npx verto-blocks add

Install a specific block:

npx verto-blocks add header-1

Install all available blocks:

npx verto-blocks add --all

List all available blocks:

npx verto-blocks list

Using Blocks in Your Application

Basic Usage

Once blocks are installed, import and use them like any other component:

import { Header1 } from "@/blocks/header/header-1";
// or
import { Header1 } from "./src/blocks/header/header-1";

function App() {
  return (
    <Header1
      component={{
        id: "header1",
        name: "header1",
        type: "header",
        variant: "standard",
        content: {
          title: "My Website",
          links: [
            { label: "Home", url: "/" },
            { label: "About", url: "/about" },
          ],
        },
      }}
    />
  );
}

Auto-Population in Verto Editor

The blocks automatically populate in your Verto.js editor:

import { VertoBlocksPlugin } from "@verto.js/blocks";
import { VertoEditor } from "@verto.js/core";

// Initialize the editor
const editor = new VertoEditor();

// Initialize the blocks plugin
const blocksPlugin = new VertoBlocksPlugin();

// Auto-register all installed blocks
await blocksPlugin.registerWithEditor(editor);

// Optional: Watch for changes during development
if (process.env.NODE_ENV === "development") {
  blocksPlugin.watch((event, block) => {
    console.log(`Block ${event}: ${block.name}`);
    // Handle hot-reload or re-registration
  });
}

Using with Next.js App Router

// app/editor/page.tsx
import { VertoBlocksPlugin } from "@verto.js/blocks";
import { VertoEditor } from "@verto.js/core";

export default async function EditorPage() {
  const blocksPlugin = new VertoBlocksPlugin();
  const blocks = await blocksPlugin.getInstalledBlocks();

  return <VertoEditor initialBlocks={blocks} />;
}

Using with Vite/React

// src/App.tsx
import { useEffect, useState } from "react";
import { VertoBlocksPlugin } from "@verto.js/blocks";
import { VertoEditor } from "@verto.js/core";

function App() {
  const [editor, setEditor] = useState(null);

  useEffect(() => {
    const initEditor = async () => {
      const editor = new VertoEditor();
      const blocksPlugin = new VertoBlocksPlugin();

      await blocksPlugin.registerWithEditor(editor);
      setEditor(editor);
    };

    initEditor();
  }, []);

  return <div>{/* Your app */}</div>;
}

Configuration

The verto.config.json file controls how blocks are installed:

{
  "blocksPath": "./src/blocks",
  "typescript": true,
  "aliases": {
    "@/blocks": "./src/blocks",
    "@/lib": "./src/lib"
  }
}

Configuration Options

• blocksPath: Where to install block components (default: "./src/blocks")
• typescript: Whether you're using TypeScript (default: true)
• aliases: Path aliases for imports (automatically configured)

CLI Commands

npx verto-blocks init

Initialize Verto blocks in your project. Sets up configuration and directories.

npx verto-blocks add [block-name]

Add blocks to your project. Without a block name, opens interactive selection.

Options:

• -o, --overwrite: Overwrite existing blocks without prompting
• -a, --all: Install all available blocks

npx verto-blocks list

List all available blocks organized by category.

Plugin API

VertoBlocksPlugin

Main plugin class for integrating with Verto.js editor.

const plugin = new VertoBlocksPlugin(options?: {
  registryPath?: string;  // Custom registry path
  blocksPath?: string;    // Custom blocks directory
});

Methods

getInstalledBlocks(): Promise<Block[]>

Returns all installed blocks with their configurations.

const blocks = await plugin.getInstalledBlocks();

registerWithEditor(editor: VertoEditor): Promise<void>

Automatically registers all installed blocks with the editor.

await plugin.registerWithEditor(editor);

generateBlocksManifest(): Promise<void>

Generates a manifest file for build-time optimization.

await plugin.generateBlocksManifest();

watch(callback: Function): void

Watch for changes to installed blocks (useful for development).

plugin.watch((event, block) => {
  console.log(`Block ${event}: ${block.name}`);
});

Customizing Blocks

Since blocks are installed directly into your project, you can customize them:

1. Modify styles: Edit the Tailwind classes or CSS
2. Change behavior: Update component logic
3. Adjust schema: Modify the componentConfig export
4. Add features: Extend the component with new functionality

Example customization:

// src/blocks/header/header-1.tsx
export function Header1({ component }: HeaderProps) {
  // Add your custom logic here
  const [isScrolled, setIsScrolled] = useState(false);

  useEffect(() => {
    // Custom scroll behavior
    const handleScroll = () => {
      setIsScrolled(window.scrollY > 50);
    };

    window.addEventListener("scroll", handleScroll);
    return () => window.removeEventListener("scroll", handleScroll);
  }, []);

  // Rest of the component...
}

File Structure

After installation, your project structure will look like:

your-project/
├── src/
│   ├── blocks/           # Installed blocks
│   │   ├── header/
│   │   │   ├── header-1.tsx
│   │   │   └── header-2.tsx
│   │   ├── hero/
│   │   │   └── hero-1.tsx
│   │   └── shared/       # Shared components
│   │       └── media-display.tsx
│   └── lib/
│       └── utils.ts      # Utility functions
├── .verto/
│   └── blocks-registry.json  # Installed blocks registry
└── verto.config.json     # Configuration

Block Component Interface

Each block component receives a standardized props interface:

interface BlockProps {
  component: {
    id: string;
    name: string;
    type: string;
    variant: string;
    content: Record<string, any>; // Block-specific content
  };
}

Updating Blocks

To update a block to the latest version:

npx verto-blocks add header-1 --overwrite

Note: This will overwrite your local changes. Make sure to backup any customizations first.

TypeScript Support

All blocks are written in TypeScript and include type definitions. The plugin provides full TypeScript support:

import type { Block, BlockConfig } from "@verto.js/blocks";

Development Workflow

1. Install blocks you need:

   npx verto-blocks add header-1 hero-1 footer-1

2. Customize the blocks in your src/blocks directory

3. Use the blocks in your pages/components

4. Blocks auto-populate in the Verto editor via the plugin

5. Commit your customized blocks to version control

Troubleshooting

Blocks not showing in editor

Ensure the plugin is properly initialized:

const plugin = new VertoBlocksPlugin();
await plugin.registerWithEditor(editor);

Import errors

Check your tsconfig.json or jsconfig.json has the correct path aliases:

{
  "compilerOptions": {
    "paths": {
      "@/blocks/*": ["./src/blocks/*"],
      "@/lib/*": ["./src/lib/*"]
    }
  }
}

Missing dependencies

Some blocks may require additional npm packages. The CLI will attempt to install them automatically, but you can install manually if needed:

npm install lucide-react

Contributing

To contribute new blocks or improvements, please visit our GitHub repository.

License

Unlicensed - will hopefully change soon

Support

For issues, questions, or suggestions: