​

Contributing to Opal Editor

​

Getting Started

​

Prerequisites

• Node.js: Version 22.19.0 or higher (see ~/workspace/source/package.json:196-198)
• npm: Comes with Node.js
• Git: For version control

​

Development Setup

1. Clone the repository

git clone https://github.com/rbbydotdev/opal.git
cd opal

2. Install dependencies

npm install

3. Start the development server

npm run dev

​

Development Scripts

​

Code Style and Conventions

​

TypeScript Configuration

• Strict mode enabled: All strict type-checking options are on
• No unchecked indexed access: Always check for undefined when accessing array/object properties
• No implicit any: All types must be explicitly defined
• Path aliases: Use @/* to import from src/*

​

ESLint Rules

• No floating promises: All promises must be properly awaited or handled
• React Hooks exhaustive deps: Dependency arrays must be complete
• Custom hooks: useAsyncEffect, useRemoteResource, useRunner, and useResource are checked for dependencies
• Unused variables: Variables starting with _ are ignored

npm run lint

​

Code Formatting

• Use 2 spaces for indentation
• Use double quotes for strings
• Add trailing commas where valid
• Format on save is recommended

​

Naming Conventions

• Components: PascalCase (e.g., WorkspaceList.tsx)
• Files: camelCase for utilities, PascalCase for components
• Variables: camelCase
• Constants: UPPER_SNAKE_CASE for true constants
• Types/Interfaces: PascalCase

​

Development Workflow

​

1. Find an Issue or Feature

• Check the GitHub Issues for open tasks
• Look for issues labeled good first issue or help wanted
• Join the Discord server to discuss ideas
• Comment on an issue to indicate you’re working on it

​

2. Create a Branch

git checkout -b feature/workspace-templates
git checkout -b fix/editor-cursor-jump
git checkout -b docs/update-api-reference

• feature/ - New features
• fix/ - Bug fixes
• docs/ - Documentation updates
• refactor/ - Code refactoring
• test/ - Test additions or updates

​

3. Make Your Changes

• Write clean, well-documented code
• Follow the existing code style and patterns
• Add comments for complex logic
• Update documentation as needed
• Ensure TypeScript types are correct

​

4. Test Your Changes

npm run typecheck

npm run lint

npm test

​

5. Commit Your Changes

git add .
git commit -m "feat: add workspace template selection"
git commit -m "fix: resolve cursor jump in markdown editor"
git commit -m "docs: update API reference for build service"

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• style: - Code style changes (formatting, etc.)
• refactor: - Code refactoring
• test: - Test updates
• chore: - Build process or tooling changes

​

Pull Request Process

​

1. Push Your Branch

git push origin feature/your-feature-name

​

2. Create a Pull Request

1. Go to github.com/rbbydotdev/opal
2. Click “Pull requests” > “New pull request”
3. Select your branch
4. Fill out the PR template with:
   • Description: What does this PR do?
   • Motivation: Why is this change needed?
   • Changes: What files/components were modified?
   • Testing: How was this tested?
   • Screenshots: For UI changes (if applicable)

​

3. PR Requirements

• ✅ All tests must pass
• ✅ Code must pass TypeScript checks (npm run typecheck)
• ✅ Code must pass ESLint checks (npm run lint)
• ✅ No merge conflicts
• ✅ Description clearly explains the changes
• ✅ At least one maintainer approval

​

4. Address Review Feedback

• Respond to review comments
• Make requested changes
• Push updates to your branch (PR will update automatically)
• Re-request review after making changes

​

5. Merge

​

Project Structure

src/
├── components/       # React components
├── data/            # Data layer (Dexie, DAO)
├── services/        # Business logic services
├── lib/             # Utility functions
├── hooks/           # Custom React hooks
└── routes/          # Application routes (Tanstack Router)

playwright-tests/    # E2E tests
public/              # Static assets

​

Architecture Notes

• Local-first: Uses IndexedDB (Dexie) and OPFS for storage
• Git integration: Built on isomorphic-git
• State management: Valtio for reactive state
• Routing: Tanstack Router
• UI: Radix UI + Tailwind CSS
• Editor: MDX Editor (WYSIWYG) + CodeMirror (raw markdown)

​

Getting Help

• Discord: Join our community
• Issues: GitHub Issues
• Discussions: GitHub Discussions

​

Code of Conduct

• Be respectful and inclusive
• Provide constructive feedback
• Focus on what is best for the community
• Show empathy towards other community members

​

License