Skip to main content
This guide will help you set up Opal Editor for local development.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js: Version 22.19.0 or higher (specified in package.json:196)
  • npm: Comes with Node.js
  • Git: For version control
Opal Editor requires Node.js 22.19.0 or later. Check your version with node --version.

​
Installation

1

Clone the repository

git clone https://github.com/yourusername/opal-editor.git
cd opal-editor
2

Install dependencies

npm install
This will install all dependencies and automatically run patch-package via the postinstall script to apply necessary patches.
3

Start the development server

npm run dev
The application will be available at http://localhost:3000 (configured in vite.config.ts:64).

​
Development Commands

Opal Editor provides several npm scripts for development:

​
Core Development

# Start development server with Vite
npm run dev

# Start both app and workers in parallel
npm run dev:all

# Build the entire application
npm run build

# Preview production build
npm run preview

​
Worker Development

# Build workers with logging disabled
npm run build:workers

# Build workers with logging enabled (development)
npm run build:workers:dev

# Watch worker logs
npm run dev:workerlog

​
Testing

# Run end-to-end tests with Playwright
npm test

# Run tests in headed mode (see browser)
npm run test:headed

# Run tests in debug mode
npm run test:debug

# Open Playwright test UI
npm run test:ui

# Run unit tests
npm run test:unit

​
Code Quality

# Run ESLint
npm run lint

# Type check without emitting files
npm run typecheck

# Type check in watch mode
npm run dev:tsc

​
Deployment

# Deploy to Cloudflare Pages
npm run deploy

# Start Cloudflare Pages dev server
npm run pages:dev

​
Project Structure

Understanding the project structure will help you navigate the codebase: 
src/
├── api/                    # API integrations (GitHub, Netlify, Vercel, AWS, Cloudflare)
├── auth/                   # Authentication providers
├── components/             # React components
│   ├── filetree/          # File tree navigation
│   ├── ui/                # shadcn/ui components
│   ├── build-modal/       # Build configuration UI
│   ├── publish-modal/     # Publishing UI
│   └── ...
├── data/                   # Data layer and persistence
│   ├── dao/               # Data Access Objects
│   ├── db/                # Dexie (IndexedDB) setup
│   ├── disk/              # Virtual filesystem abstraction
│   └── fs/                # Filesystem implementations
├── editors/                # Editor implementations
│   ├── markdown/          # WYSIWYG markdown editor
│   ├── source/            # Source code editor
│   └── history/           # Edit history
├── features/               # Feature modules
│   ├── git-repo/          # Git integration
│   ├── live-preview/      # Live preview functionality
│   ├── search/            # Search features
│   └── ...
├── lib/                    # Shared utilities
│   ├── service-worker/    # Service worker logic
│   ├── markdown/          # Markdown processing
│   └── events/            # Event system
├── routes/                 # Tanstack Router pages
├── services/               # Business logic services
│   ├── build/             # Static site generation
│   ├── deploy/            # Deployment services
│   └── import/            # Import functionality
├── webworkers/             # Web worker implementations
├── workspace/              # Workspace management
└── main.tsx                # Application entry point

​
Key Directories Explained

​
/src/data

Contains the data layer with IndexedDB setup using Dexie, DAOs for workspaces, builds, deployments, and the virtual filesystem abstraction.

​
/src/lib/service-worker

Implements the service worker using Hono router (sw-hono.ts:1) for handling requests like image uploads, markdown rendering, and workspace downloads - enabling the no-server-required architecture.

​
/src/workspace

Core workspace management, including the Workspace class (Workspace.ts:74) that orchestrates disk, Git repo, and image cache.

​
/src/services/build

Static site generation with support for various template engines (Eleventy, Mustache, Nunjucks, Liquid, EJS).

​
Running Tests

Opal Editor uses Playwright for end-to-end testing: 
# Run all tests
npm test

# Run in UI mode for debugging
npm run test:ui

# Run in headed mode to see the browser
npm run test:headed

# Debug specific test
npm run test:debug
Unit tests can be run with: 
npm run test:unit

​
Development Tips

​
Service Worker Development

  • Service workers are enabled by default in development
  • The service worker controls requests at http://localhost:3000
  • Headers are configured in vite.config.ts:65-69 to allow service worker scope
  • Check src/lib/service-worker/sw-hono.ts for request routing

​
Hot Module Replacement

Vite’s HMR is enabled by default. Changes to React components will hot-reload without losing state.

​
React Compiler

Opal Editor uses the React 19 compiler (babel-plugin-react-compiler) for automatic memoization. This is configured in vite.config.ts:40-44.

​
Path Aliases

The project uses @/ as an alias for src/ (configured in vite.config.ts:60 and tsconfig.json:29): 
import { Workspace } from '@/workspace/Workspace';

​
Browser Compatibility

Opal Editor requires modern browser features:
  • IndexedDB or OPFS (Origin Private File System)
  • Service Workers
  • Web Workers
  • ES2017+ JavaScript features

​
Troubleshooting

​
Installation Issues

If npm install fails:
  1. Ensure you’re using Node.js 22.19.0 or higher
  2. Clear npm cache: npm cache clean --force
  3. Delete node_modules and package-lock.json, then reinstall

​
Service Worker Issues

If the service worker isn’t working:
  1. Unregister existing service workers in DevTools → Application → Service Workers
  2. Hard refresh the page (Cmd/Ctrl + Shift + R)
  3. Check the Console for service worker registration errors

​
Build Errors

If the build fails: 
# Clean build and rebuild
rm -rf dist
npm run build

​
Next Steps

Now that your development environment is set up:
  1. Read the Architecture Guide to understand the codebase structure
  2. Check open issues on GitHub to find contribution opportunities
  3. Join the Discord community for developer discussions
Start by exploring the codebase with the search feature (Cmd/Ctrl + P) or browse the file tree to familiarize yourself with the structure.

Build docs developers (and LLMs) love

Get started for freeTalk to us