VexBlocks
DocumentationInstallation

Installation

Get VexBlocks up and running in your project

Requirements

Before you begin, make sure you have the following installed:

Node.js 18.17 or higher
Check with node --version
pnpm 9.0 or higher
Install with npm install -g pnpm
Git
For version control

Installation Steps

Create a New Project

Run the VexBlocks CLI to create a new project. This will set up a complete Turborepo monorepo with all the necessary configuration:

npx @vexblocks/cli init

Follow the interactive prompts to configure your project.

Navigate to Project

Change into your newly created project directory:

cd my-vexblocks-project

Install Dependencies

Install all required npm packages using pnpm:

pnpm install

Add VexBlocks Packages

Add the CMS dashboard, backend, and other packages:

npx @vexblocks/cli add all

This installs the CMS dashboard, Convex backend, shared utilities, and type generator.

Configure VexBlocks

Update your application settings in packages/backend/convex/cms/vexblocks.config.ts:

const config: VexBlocksConfig = {
  appName: "My App",
  email: {
    fromName: "My App",
    fromAddress: "noreply@yourdomain.com",
  },
}

These settings control your application name (used in email subjects) and the sender information for transactional emails.

Set Up Convex

Create a Convex account and initialize your backend:

cd packages/backend
npx convex dev

This will prompt you to log in and create a new Convex project. Copy the deployment URL when provided.

Configure Environment Variables

Copy the environment example file and fill in your Convex deployment details:

# In the root of your project
cp .env.example .env.local

# Add your Convex URL
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
CONVEX_DEPLOYMENT=your-deployment
SITE_URL=http://localhost:3001

Start Development

Run the development server for all packages:

pnpm dev

This will start:

  • CMS Dashboard at http://localhost:3001
  • Convex backend (watching for changes)
  • Any other apps in your workspace

Success! Your VexBlocks CMS is now running. Visit http://localhost:3001 to access the dashboard.

Adding to Existing Project

If you already have a Turborepo project and want to add VexBlocks to it:

# In your Turborepo root
npx @vexblocks/cli init

# Then add packages
npx @vexblocks/cli add all

The CLI will detect your existing Turborepo and integrate VexBlocks seamlessly.

Optional: Cloudflare Images

For the media library feature, you can optionally set up Cloudflare Images:

  1. Create a Cloudflare account
  2. Enable Cloudflare Images in your dashboard
  3. Add your account ID and API token to .env.local:
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_SECRET_TOKEN=your-api-token

Troubleshooting

Port Already in Use

If port 3001 is already in use, you can change it in apps/cms/package.json:

"scripts": {
  "dev": "next dev --port 3002"
}

Convex Connection Errors

Make sure:

  • Your NEXT_PUBLIC_CONVEX_URL is correctly set
  • The Convex backend is running (npx convex dev in packages/backend)
  • You're logged in to Convex

pnpm Install Fails

Try clearing the pnpm cache and reinstalling:

pnpm store prune
pnpm install

Next Steps