Add Blocks

The add command downloads a backend block from the Blockend registry and installs it directly into your project.

Each block is framework-aware, TypeScript-first, and follows your project's existing configuration defined in blockend.json.

npx blockend add <block>

For example:

npx blockend add auth

If no block name is provided, Blockend launches an interactive block picker.

npx blockend add

How It Works

When you run the command, Blockend performs several steps automatically.

1. Finds your blockend.json configuration.
2. Connects to the Blockend Registry.
3. Retrieves all blocks available for your framework.
4. Lets you select a block (if one isn't provided).
5. Detects the appropriate storage variant.
6. Installs missing dependencies.
7. Downloads the block source code.
8. Writes the files into your configured blocks directory.

Everything happens automatically—no copying files or manually installing packages.

Interactive Block Selection

Running the command without a block name opens an interactive selector.

npx blockend add

Example:

? Which backend block would you like to inject?

❯ auth
  pagination
  upload
  cache
  logger

Only blocks compatible with your configured framework are displayed.

Framework Aware

Every block is generated specifically for your backend framework.

Currently supported environments include:

• Express.js
• Fastify
• Next.js (App Router)
• Hono

If a block is unavailable for your framework, Blockend will notify you before downloading anything.

Storage Variants

Some blocks support multiple storage implementations.

For example:

• Memory
• Redis
• Database

If multiple variants are available, Blockend asks which implementation you want.

? Which architectural storage variant do you want?

❯ Memory
  Redis

If Redis is enabled in your blockend.json, the Redis variant is selected automatically whenever available.

Automatic Dependency Installation

Many backend blocks require external packages.

Before downloading a block, Blockend checks your project's dependencies.

If required packages are missing, you'll be prompted to install them.

Example:

Missing required infrastructure packages:

- redis
- zod

Would you like the CLI to install them automatically?

❯ Yes

Blockend automatically detects your package manager.

Supported package managers:

• pnpm
• npm

After installation completes, the block download continues automatically.

Generated Files

Downloaded files are placed inside the blocks directory configured during initialization.

Example:

src/
└── blocks/
    └── auth/
        ├── auth.ts
        └── store-redis.ts

Simple blocks may generate a single file.

src/
└── blocks/
    └── pagination.ts

Existing Files

If a block already exists, Blockend never overwrites it without confirmation.

Example:

Block component already exists.

Overwrite existing files?

❯ No

Selecting No safely aborts the operation and preserves your code.

Examples

Generate an authentication block:

npx blockend add auth

Generate a pagination block:

npx blockend add pagination

Generate an upload block:

npx blockend add upload

Open the interactive selector:

npx blockend add

Requirements

Before using the add command, make sure your project has been initialized.

npx blockend init

Blockend also requires:

• A valid blockend.json
• A TypeScript project
• A supported backend framework
• Internet access to download blocks from the Blockend Registry

Common Errors

blockend.json not found

blockend.json not found.
Run 'npx blockend init' first.

Initialize your project before adding blocks.

npx blockend init

Block not found

Block "auth" does not exist.

The requested block either doesn't exist or hasn't been published yet.

Run the interactive command to see all available blocks.

npx blockend add

Unsupported Framework

The block "upload" does not support your environment.

Some blocks are framework-specific and may not be available for every backend.

Failed to Download Registry

Failed to fetch the component registry.

Verify your internet connection and try again.

Next Steps

After generating a block, import it into your application and customize it as needed.

Every generated block is fully owned by you—there are no runtime dependencies on Blockend.