Where to Put Your Code
Plugin development is the primary path for racletteJS application work.
Decision Table
| I want to... | Put it in... | Why |
|---|---|---|
| Add a REST API endpoint | plugins/<name>/backend/routes/ | Plugins are the supported extension point for business logic. |
| Add backend business logic | plugins/<name>/backend/*.service.ts | Keeps domain logic versionable and plugin-scoped. |
| Add a frontend widget | plugins/<name>/frontend/widgets/<WidgetName>/ | Widgets are discovered and rendered through the plugin runtime contract. |
| Add a DB model/schema | plugins/<name>/backend/*.model.ts + *.schema.ts | Backend data contracts live in plugin backend files. |
| Add runtime npm dependency | yarn add-package <target> <pkg> | Updates both local IDE deps and runtime service deps (packages.json). |
| Share app-level constants/types | shared/ | Shared folder is synced into app-scoped shared paths. |
| Add app-level translations | i18n/ | App i18n is merged as app-scoped translations. |
| Add app-level code without override risk | services/*/src/app/* | app namespace is reserved app space and avoids accidental core replacement. |
| Override framework internals | services/backend/* or services/frontend/* | Escape hatch only; full file replacement and migration risk. |
Recommended Default
- Start each business feature as a plugin.
- A plugin can contain several datatypes and we recommend clustering by them.
- Use service overrides only if no plugin contract can solve the task.
- Prefer plugin code, because plugins can be reused across future apps.
- App-specific code can live outside plugins, but racletteJS is optimized for reusable plugin-first architecture.
Reusability and Overrides
- It is possible to use service overrides to add shared UI pieces for your app.
- This can reduce plugin portability because plugins may start depending on app-local runtime additions.
- There is currently no dedicated dependency management concept for this override-driven shared layer.
- If you only want to add app code (not replace core behavior), prefer
services/*/src/app/*to avoid accidental overrides.