Contributing
How to contribute
Nautilus is community-built and small enough to be approachable. Templates and icons are genuinely easy first contributions.
Set up
git clone https://github.com/Somilg11/nautilus.git cd nautilus npm install npm run dev # before opening a PR — CI runs exactly this npm run lint && npm run typecheck && npm test && npm run build
Where things live
| Area | Path | Difficulty |
|---|---|---|
| Templates | src/lib/templates/ | Easy |
| Icons | src/components/nodes/node-icons.tsx | Easy |
| Docs | docs/, src/app/docs/ | Easy |
| Canvas behaviour | src/components/canvas.tsx | Medium |
| Simulation engine | src/lib/flow-execution.ts | Involved |
| AI providers | src/lib/ai-client.ts | Involved |
Conventions worth knowing
| Rule | Why |
|---|---|
| One listener per nautilus-* event | Toolbar buttons dispatch window events. Binding one twice is how paste once inserted two copies of everything. |
| Never persist transient state | Anything written into node data lands in undo history, autosave, exports and share links. |
| Validate untrusted input | Imports, share links and AI output all pass through src/lib/diagram-io.ts. |
| Use reactflow v11 | react-flow-renderer is the unmaintained v10 package and pins React to 18. |
| Conventional commits | feat:, fix:, docs:, refactor:, test:, chore: |
Testing
The pure parts — the execution planner and the diagram validator — are unit-tested with Vitest. Any change to their behaviour should come with a test.
npm test # single run npm run test:watch # watch mode
Start small
A focused pull request gets reviewed quickly. If a change touches the JSON format or the event contract, open an issue first so the shape can be agreed before you write it.