Open this when laying out a new workspace, adding a feature or an Nx library, or wiring the lint rule that enforces the dependency direction. Verified 2026-09 against https://angular.dev/style-guide and https://nx.dev/features/enforce-module-boundaries.
1. Single-app CLI workspace
src/app/
app.ts app.config.ts app.routes.ts # root component, providers, top-level lazy routes
core/
auth/ auth-store.ts auth-interceptor.ts auth-guard.ts
http/ api-base-url.ts error-interceptor.ts
config/ app-config.ts # InjectionToken + provideAppInitializer loader
errors/ global-error-handler.ts
layout/ shell.ts nav.ts
features/
orders/
orders.routes.ts # the ONLY file the router imports
index.ts # public API: what other features may import
pages/ order-list.ts order-detail.ts # routed, inject stores/services
components/ order-row.ts order-status-badge.ts # input()/output() only
data/ orders-api.ts orders-store.ts
model/ order.ts order-totals.ts # types + pure functions
shared/
ui/ button/ dialog/ empty-state/ # presentational, zero feature knowledge
util/ format-money.ts date-range.ts # pure functions, no DI
Dependency direction: features → shared, core · core → shared · shared → nothing · feature → feature only through index.ts.
Why index.ts and not deep imports: it is the only cheap way to change a feature's internals without a cross-team PR, and it is the thing a lint rule can check.
2. Enforcing it in a CLI workspace
eslint-plugin-boundaries (install eslint-plugin-boundaries), in eslint.config.js:
// eslint.config.js (flat config)
import boundaries from 'eslint-plugin-boundaries';
export default [
{
files: ['src/**/*.ts'],
plugins: { boundaries },
settings: {
'boundaries/elements': [
{ type: 'core', pattern: 'src/app/core/*' },
{ type: 'shared', pattern: 'src/app/shared/*' },
{ type: 'feature', pattern: 'src/app/features/*', capture: ['name'] },
],
},
rules: {
'boundaries/element-types': ['error', {
default: 'disallow',
rules: [
{ from: 'feature', allow: ['shared', 'core', ['feature', { name: '${from.name}' }]] },
{ from: 'core', allow: ['shared'] },
{ from: 'shared', allow: ['shared'] },
],
}],
},
},
];
Run it in CI as ng lint. An unenforced boundary is gone within two sprints.
A cheaper stopgap while you adopt the plugin: no-restricted-imports with a pattern blocking **/features/*/!(index) — it catches deep imports but not the direction.
3. Nx workspace
Same layers, expressed as libraries with tags. One app, many libraries:
apps/portal/
libs/orders/feature-list/ tags: scope:orders, type:feature
libs/orders/data-access/ tags: scope:orders, type:data-access
libs/orders/ui/ tags: scope:orders, type:ui
libs/orders/model/ tags: scope:orders, type:util
libs/shared/ui/ tags: scope:shared, type:ui
libs/shared/util/ tags: scope:shared, type:util
| Library type | Contains | May depend on |
|---|---|---|
feature |
routed pages, smart components, the feature's routes file | data-access, ui, util |
data-access |
API services, stores, resources | util |
ui |
presentational components, directives, pipes | util |
util |
types, pure functions, constants | util |
Tag rules in eslint.config.js via @nx/enforce-module-boundaries:
'@nx/enforce-module-boundaries': ['error', {
depConstraints: [
{ sourceTag: 'type:feature', onlyDependOnLibsWithTags: ['type:feature', 'type:data-access', 'type:ui', 'type:util'] },
{ sourceTag: 'type:data-access', onlyDependOnLibsWithTags: ['type:data-access', 'type:util'] },
{ sourceTag: 'type:ui', onlyDependOnLibsWithTags: ['type:ui', 'type:util'] },
{ sourceTag: 'type:util', onlyDependOnLibsWithTags: ['type:util'] },
{ sourceTag: 'scope:orders', onlyDependOnLibsWithTags: ['scope:orders', 'scope:shared'] },
{ sourceTag: 'scope:shared', onlyDependOnLibsWithTags: ['scope:shared'] },
],
}],
Two constraint families — type:* (what a library may reuse) and scope:* (which domain may see which) — cover almost every real rule. Add a third family only when a rule cannot be expressed with these.
Use Nx when at least one is true: more than one deployable app, libraries with different owners, or CI times that need affected-only builds. One app with four features does not need Nx; the folder tree plus a boundary lint rule gives the same discipline with no extra tooling.
4. File naming — pick once, configure the schematics
The current style guide names the file after the class with no type suffix: class UserProfile → user-profile.ts / user-profile.html / user-profile.css; OrdersApi → orders-api.ts; authGuard → auth-guard.ts. Angular CLI 20 and later scaffold this way by default.
New repos: take the default. Nothing to configure.
Existing repos on .component.ts / .service.ts: keep them — a rename touches every import and every test — and pin the schematics so generated files match:
// angular.json
"schematics": {
"@schematics/angular:component": { "type": "component", "changeDetection": "OnPush" },
"@schematics/angular:service": { "type": "service" },
"@schematics/angular:directive": { "type": "directive" },
"@schematics/angular:guard": { "type": "guard" }
}
Whichever you choose, write it in ARCHITECTURE.md and match the always-on instructions file, which selects files by folder rather than suffix so both conventions load the same rules. Never mix the two inside one project: a mixed tree makes every "where is the component for X" search a two-pattern search.
If you do decide to rename, do it as one mechanical PR with no behaviour change, and land it on a quiet branch day.
5. Where new code goes — the three questions
- Does anything outside this feature use it? No → inside the feature. Yes →
shared/ui(component) orshared/util(function). - Does it need DI or app state? No →
model/orshared/utilas a pure function; it becomes trivially testable. - Does exactly one instance exist for the whole app? Yes →
core/, provided inapp.config.ts.
A file that answers "yes" to (1) and "yes" to (2) is usually a feature that has not been named yet — give it a folder rather than pushing it into shared.