ignis/CONTRIBUTING.md

Contributing to Ignis

Thanks for your interest in contributing. Here are some ways you can help.

Reporting Plugin Compatibility Issues

Testing plugins and reporting what works (or doesn't) is one of the most valuable contributions right now. When a plugin doesn't work, the browser console usually contains the information needed to diagnose the problem.

How to file a useful compatibility report

1. Open the browser dev tools (F12 or Ctrl+Shift+I)
2. Go to the Console tab
3. Enable the plugin or trigger the failing action
4. Look for errors, especially lines starting with:
   • [ignis] Unshimmed require: <module> - a Node.js module the plugin needs that Ignis doesn't provide yet
   • [shim:MISS] <module>.<property> - a property or method on a shimmed module that isn't implemented
   • Plugin failure: <plugin-id> - Obsidian caught a crash from the plugin
5. Copy the full error including the stack trace

What to include in the issue

• Plugin name and version
• What you tried to do
• What happened (error, crash, nothing, partial functionality)
• The console output (errors and shim warnings)
• Whether the plugin loads at all or fails immediately

Example of a useful report

Plugin: Templater v1.18.4 Status: Broken on load

Console shows:

[ignis] Unshimmed require: util
[shim:MISS] UNKNOWN(util).promisify - property not found on shim
Plugin failure: templater-obsidian TypeError: t is not a function

The plugin needs util.promisify which isn't shimmed yet.

This kind of report makes it straightforward to add the missing shim.

Code Contributions

If you want to contribute code:

1. Fork the repo and create a branch for your change
2. Run npm install once at the repo root (npm workspaces)
3. Run npm run dev to build and start the server
4. Test your change in the browser with at least one vault open
5. Run npm test and make sure the whole suite passes
6. Keep PRs focused - one fix or feature per PR

Changes to deliberate behavior (the fs shim's caching and write model, the proxy's request handling, anything documented as a design decision) start as an issue, not a PR. Open the issue first so the approach can be discussed; a patch against an undiscussed design change will be closed on this basis.

Project structure

• packages/shim/ - Browser shims for Node.js and Electron APIs
• packages/ui/ - Svelte UI components (vault manager, dialogs)
• packages/bridge/ - The ignis-bridge Obsidian plugin (settings, file actions)
• packages/server-core/ - Shared server helpers (path guards, watcher, WebSocket)
• apps/ignis-server/ - Express server, Docker image, demo mode
• apps/ignis-server/server/plugins/ - Server plugin packages (e.g., headless-sync)

See ARCHITECTURE.md for more detail.

Adding a new shim

If a plugin needs a Node.js module that isn't shimmed:

1. Create the shim in packages/shim/src/node/<module>.js
2. Export the functions the plugin needs (stub what you can't implement)
3. Register it in packages/shim/src/require.js (import + add to rawRegistry)
4. Build and test with the plugin that needed it