1---2name: backstage-plugins3description: Apply Backstage plugin and module boundaries for frontend, backend, common, node, and extension-point code. Use when editing plugin or Backstage package TypeScript.4---56<!-- Generated from harness/github-copilot/plugins/backstage-expert/instructions/backstage-plugins.instructions.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->78# Backstage Plugin Conventions910These instructions apply to Backstage plugin and package implementation. They are authoritative11for plugin boundaries, frontend mode, backend registration, extension points, configuration, and12package-local validation in matched files; Backstage core contributor rules and repository-local13package policy win on conflict.1415## Frontend and Backend Systems1617- Declare frontend mode as `new`, `legacy`, or `dual` before editing.18- Use `createFrontendPlugin` for new frontend work.19- Preserve `createPlugin` only for explicit legacy support; use a documented alpha entry point20 when dual support is required.21- Use `createBackendPlugin` for backend plugins and `createBackendModule` for modules.22- Extend plugins through public extension points, not internal imports.2324## Package Design2526- Keep public exports minimal and update API reports or equivalent checks when public APIs change.27- Put shared types and schemas in common packages only when multiple packages consume them.28- Keep backend-only clients and extension points out of browser bundles.29- Declare config, permissions, auth assumptions, and external routes in package documentation.3031## Conventions3233| Rule | Rationale |34| --- | --- |35| Keep implementation independently testable. | App-only wiring hides plugin regressions. |36| Use lazy loading for large routable frontend surfaces. | It protects app startup performance. |37| Validate inputs and authorize backend operations. | Identity alone is not authorization. |3839## Do / Do Not4041| Do | Do not |42| --- | --- |43| Run package-local lint, typecheck, tests, and build scripts. | Run a Backstage core root build as routine validation. |44| Bind external routes explicitly. | Reach into another plugin's internal route definitions. |45| Preserve compatibility promised by the selected mode. | Silently convert a dual plugin to new-only. |4647## Checklist Before Opening a PR4849- [ ] Frontend mode and Backstage version are explicit.50- [ ] Plugin, module, and extension-point boundaries use public APIs.51- [ ] Config, auth, permissions, and route contracts are documented.52- [ ] Package-local validation and relevant API reports pass.53- [ ] No secrets, internal endpoints, or unrelated edits are present.5455## References5657- [New frontend plugin system](https://github.com/backstage/backstage/blob/master/docs/frontend-system/building-plugins/01-index.md)58- [New backend plugins and modules](https://github.com/backstage/backstage/blob/master/docs/backend-system/building-plugins-and-modules/01-index.md)