Opennextjs CLI

---

Overview

OpenNext.js CLI is a comprehensive, interactive command-line tool that simplifies setting up and managing OpenNext.js projects for Cloudflare Workers. Built with modern UX principles using @clack/prompts (same as next-forge), it provides a beautiful, intuitive interface for project setup, configuration, deployment, and maintenance.

What is OpenNext.js?

OpenNext.js is an open-source adapter that enables deploying Next.js applications to various platforms, including Cloudflare Workers. This CLI tool automates the entire setup and configuration process, making it as easy as create-next-app.

Packages

This monorepo contains 2 npm packages that share the same GitHub repository but are published separately:

1. @jsonbored/opennextjs-cli - CLI Tool

The main command-line interface for setting up and managing OpenNext.js projects.

Installation:

npm install -g @jsonbored/opennextjs-cli
# or
pnpm add -g @jsonbored/opennextjs-cli

Alias: onjs (shorter command)

Documentation: See packages/opennextjs-cli/README.md for complete CLI documentation.

2. @jsonbored/opennextjs-mcp - MCP Server

Model Context Protocol server that enables AI tools to interact with OpenNext.js projects.

Installation:

npm install -g @jsonbored/opennextjs-mcp

Documentation: See packages/opennextjs-mcp/README.md for complete MCP documentation.

Note: The MCP server is automatically configured when you run opennextjs-cli mcp setup.

Quick Start

Install CLI

npm install -g @jsonbored/opennextjs-cli
# or use the alias
onjs --version

Create a New Project

opennextjs-cli init my-project
# or
onjs init my-project

Add to Existing Project

cd your-existing-nextjs-project
opennextjs-cli add
# or
onjs add

Deploy

pnpm deploy
# or
npm run deploy

Development

Prerequisites

• Node.js 18.0.0 or higher
• pnpm 8.0.0 or higher (recommended)
• Git (for version control)

Setup

# Clone repository
git clone https://github.com/JSONbored/opennextjs-cli.git
cd opennextjs-cli

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

Development Workflow

# Watch mode for CLI package
cd packages/opennextjs-cli
pnpm dev

# Watch mode for MCP package
cd packages/opennextjs-mcp
pnpm dev

# Run CLI locally
cd packages/opennextjs-cli
pnpm dev
# Then use: node dist/index.js <command>

Testing

# Run all tests
pnpm test

# Run CLI tests
cd packages/opennextjs-cli
pnpm test

# Run MCP tests
cd packages/opennextjs-mcp
pnpm test

# Run with coverage
pnpm test:coverage

Linting

# Lint all packages
pnpm lint

# Lint specific package
cd packages/opennextjs-cli
pnpm lint

Features

Core Functionality

• Interactive Setup Wizard - Beautiful step-by-step prompts for configuration
• Automatic Configuration - Generates open-next.config.ts, wrangler.toml, and more
• Smart Defaults - Best practices built-in with sensible defaults
• Dependency Management - Automatically installs required packages
• Type-Safe - Full TypeScript support with Zod validation
• Modern TUI - Beautiful terminal UI using @clack/prompts

Safety & Reliability

• Safety Checks - Comprehensive pre-operation validation
• Automatic Rollback - Reverts changes on failure
• Auto-Backup - Backs up files before modifications
• Monorepo Support - Detects and handles monorepo structures
• Path Validation - Prevents unsafe file operations

AI Integration

• MCP Server - Model Context Protocol server for AI tool integration
• Cursor/Claude Desktop - Seamless integration with AI coding assistants
• Project Insights - AI can query project status, validate configs, and more

CLI Commands

The CLI provides 15 commands for complete project management:

Project Setup

• init - Create new Next.js project with OpenNext.js
• add - Add OpenNext.js to existing project
• config - Update configuration

Project Management

• status - Show project status
• validate - Validate configuration
• doctor - Health checks with auto-fix
• setup - Configure CLI settings

Deployment & Development

• deploy - Deploy to Cloudflare
• preview - Start local preview server
• update - Update dependencies

Environment & Cloudflare

• env - Manage environment variables
• cloudflare - Manage Cloudflare authentication

Advanced

• migrate - Migrate from Vercel/Netlify
• mcp - Setup MCP server
• completion - Shell completion scripts

Full Documentation: See packages/opennextjs-cli/README.md

MCP Server

The MCP server provides AI tools with programmatic access to your OpenNext.js projects:

Tools (7)

• get_project_status - Get project information
• validate_configuration - Validate setup
• check_health - Health checks
• list_environments - List Cloudflare environments
• deploy_to_cloudflare - Deploy project
• start_preview_server - Start preview
• update_configuration - Update config

Resources (4)

• opennextjs://config/wrangler.toml - Wrangler config
• opennextjs://config/open-next.config.ts - OpenNext config
• opennextjs://config/package.json - Package config
• opennextjs://project/structure - Project structure

Prompts (3)

• setup-opennextjs-project - Setup guide
• troubleshoot-deployment - Troubleshooting
• optimize-cloudflare-config - Optimization tips

Full Documentation: See packages/opennextjs-mcp/README.md

Requirements

• Node.js 18.0.0 or higher
• pnpm 8.0.0+ (recommended) or npm/yarn/bun
• Cloudflare Account (for deployment)
• Wrangler CLI (installed automatically)

Caching Strategies

The CLI supports multiple caching strategies:

Strategy	Description	Use Case
static-assets	SSG-only, no R2 needed	Simple static sites
r2	R2 Incremental Cache	Most Next.js apps (recommended)
r2-do-queue	ISR with time-based revalidation	Dynamic content with ISR
r2-do-queue-tag-cache	Full-featured with on-demand revalidation	Complex apps with on-demand ISR

Roadmap

Completed:

• ✅ Phase 1: Core CLI commands (init, add, config, status, validate)
• ✅ Phase 2: Advanced commands (deploy, preview, update, env, cloudflare, doctor)
• ✅ Phase 5: MCP server (tools, resources, prompts)

Coming Soon:

• Phase 3: Templates, migration helpers, dry-run mode, config export/import
• Phase 4: CI/CD integration, testing setup, monitoring setup

Contributing

Contributions are welcome! Please see our contributing guidelines (coming soon).

Development Setup

# Clone repository
git clone https://github.com/JSONbored/opennextjs-cli.git
cd opennextjs-cli

# Install dependencies
pnpm install

# Build packages
pnpm build

# Run tests
pnpm test

# Run CLI locally
cd packages/opennextjs-cli
pnpm dev

Related Projects

• OpenNext.js - The core adapter that makes this possible
• OpenNext.js Cloudflare - Cloudflare-specific implementation
• Cloudflare Workers - Deployment platform
• Model Context Protocol - MCP specification

Support

• Documentation
• Report Issues
• Discussions

Credits

This tool is built for and powered by OpenNext.js, an amazing project that makes deploying Next.js to various platforms possible.

• OpenNext.js Cloudflare: https://github.com/opennextjs/opennextjs-cloudflare
• Official Documentation: https://opennext.js.org/cloudflare
• Package: @opennextjs/cloudflare on npm

---

Star History

---