2 |
3 | 
4 |
5 | ## Before We Get Started
6 |
7 | This article is not intended to be a tutorial on routing in Angular. If you are new to Routing in Angular then I highly recommend you check out one of the the following resources:
8 |
9 | - [Ultimate Courses](https://bit.ly/2WubqhW)
10 | - [Official Angular Docs](https://angular.io/guide/router)
11 |
12 | ## Background
13 |
14 | The following represents a pattern that I've developed at my day job after building several enterprise Angular applications. While most online tutorials do a great job laying out the fundamentals, I had a hard time locating articles that showed recommended conventions and patterns for large and scalable applications.
15 |
16 | With this pattern you should have a clean and concise organization for all routing related concerns in your applications.
17 |
18 | ## Prerequisites
19 |
20 | For context, this article assumes you are using the following version of Angular:
21 |
22 | - Angular v7.2.6
23 |
24 | ---
25 |
26 | ## Best Practice #1 - Create a top-level Routes array file
27 |
28 | > The official [Angular docs recommend](https://angular.io/guide/router#refactor-the-routing-configuration-into-a-routing-module) creating a full-blown `app-routing.module.ts` for your top-level routing. I have found this extra layer to be unnecessary in most cases.
29 |
30 | > HOT TIP: Only register top-level routes here, if you plan to implement feature modules, then the child routes would live underneath the respective `feature.routes.ts` file. We want to keep this top-level routes file as clean as possible and follow the component tree structure.
31 |
32 | Let's go with the following approach:
33 |
34 | 1. Create a new file named `app.routes.ts` in the root `src/app` directory. This file will hold our top-level `Routes` array. We will come back later throughout the article and fill this in. For now, let's scaffold it with the following contents:
35 |
36 | ```typescript
37 | import { Routes } from '@angular/router';
38 |
39 | export const AppRoutes: Routes = [];
40 | ```
41 |
42 | 2. Register `AppRoutes` in the `app.module.ts` file.
43 |
44 | - Import `AppRoutes` from `app.routes.ts`.
45 | - Import `RouterModule` from `@angular/router`.
46 | - Add `RouterModule.forRoot(AppRoutes)` to your `imports` array
47 |
48 | Your updated `app.module.ts` will look similar to the following:
49 |
50 | ```typescript
51 | import { NgModule } from '@angular/core';
52 | import { BrowserModule } from '@angular/platform-browser';
53 | import { RouterModule } from '@angular/router';
54 | import { AppComponent } from './app.component';
55 | import { AppRoutes } from './app.routes';
56 |
57 | @NgModule({
58 | declarations: [AppComponent],
59 | imports: [BrowserModule, RouterModule.forRoot(AppRoutes)],
60 | providers: [],
61 | bootstrap: [AppComponent]
62 | })
63 | export class AppModule {}
64 | ```
65 |
66 | ## Best Practice #2 - Create a feature-level Routes array file
67 |
68 | In similar fashion to how we constructed the `app.routes.ts` we will create a `feature.routes.ts` to list out the individual routes for this feature module. We want to keep our routes as close to the source as possible. This will be in keeping with a clean code approach, and having a good separation of concerns.
69 |
70 | 1. Create a new file named `feature/feature.routes.ts` where `feature` matches the name of your `feature.module.ts` prefix. This file will hold our feature-level `Routes` array. Keeping in mind that you would replace `Feature` with the actual name of your module, let's scaffold it with the following contents:
71 |
72 | ```typescript
73 | import { Routes } from '@angular/router';
74 |
75 | export const FeatureRoutes: Routes = [];
76 | ```
77 |
78 | 2. Register `FeatureRoutes` in the `feature/feature.module.ts` file. We will make use of the `RouterModule.forChild` import so that these routes are automatically registered with lazy loading.
79 |
80 | - Import `FeatureRoutes` from `feature.routes.ts`.
81 | - Import `RouterModule` from `@angular/router`.
82 | - Add `RouterModule.forChild(FeatureRoutes)` to your `imports` array
83 |
84 | Your updated `feature/feature.module.ts` will look similar to the following:
85 |
86 | ```typescript
87 | import { CommonModule } from '@angular/common';
88 | import { NgModule } from '@angular/core';
89 | import { RouterModule } from '@angular/router';
90 | import { FeatureRoutes } from './feature.routes';
91 |
92 | @NgModule({
93 | declarations: [],
94 | imports: [CommonModule, RouterModule.forChild(FeatureRoutes)]
95 | })
96 | export class FeatureModule {}
97 | ```
98 |
99 | An example of a `feature.routes.ts` file with child route(s) may look like the following:
100 |
101 | ```typescript
102 | import { Routes } from '@angular/router';
103 | import { FeatureOneComponent } from './feature-one.component';
104 | import { FeatureSpecificCanActivateGuard } from './_guards';
105 |
106 | export const FeatureOneRoutes: Routes = [
107 | {
108 | path: '',
109 | pathMatch: 'full',
110 | redirectTo: 'feature-one-component'
111 | },
112 | {
113 | path: 'feature-one-component',
114 | component: FeatureOneComponent,
115 | canActivate: [FeatureSpecificCanActivateGuard]
116 | }
117 | ];
118 | ```
119 |
120 | ## Best Practice #3 - Add Lazy Loaded Features to top-level Routes file
121 |
122 | > Lazy loading is the concept of deferring load of code assets (javascript, styles) until the user actually needs to utilize the resources. This can bring large performance increases to perceived load times of your application as the entire code set doesn't have to download on first paint.
123 |
124 | > Angular provides a nice way to handle this with the `loadChildren` option for a given route. More information can be found in the [official Angular docs](https://angular.io/guide/router#lazy-loading-route-configuration).
125 |
126 | Once you've created your `app.routes.ts` and `*.routes.ts` files, you need to register any feature modules that you want to load lazily.
127 |
128 | ### Per Feature Module...
129 |
130 | Update the `AppRoutes` array in the `app.routes.ts` file to include a new route the feature:
131 |
132 | ```typescript
133 | import { Routes } from '@angular/router';
134 |
135 | export const AppRoutes: Routes = [
136 | {
137 | path: 'feature',
138 | loadChildren: './feature/feature.module#FeatureModule'
139 | }
140 | ];
141 | ```
142 |
143 | By adding the above route to the array, when the user requests `/feature` in the browser, Angular lazy loads the module using the path given and then automatically registers any routes defined in the `feature.routes.ts` `FeatureRoutes` array using the `RouterModule.forChild` import.
144 |
145 | For each additional feature module, you would add another item to the `AppRoutes` array. If you have multiple features, it might look something like the following:
146 |
147 | ```typescript
148 | import { Routes } from '@angular/router';
149 |
150 | export const AppRoutes: Routes = [
151 | {
152 | path: '',
153 | pathMatch: 'full',
154 | redirectTo: 'feature-one'
155 | },
156 | {
157 | path: 'feature-one',
158 | loadChildren: './feature-one/feature-one.module#FeatureOneModule'
159 | },
160 | {
161 | path: 'feature-two',
162 | loadChildren: './feature-two/feature-two.module#FeatureTwoModule'
163 | }
164 | ];
165 | ```
166 |
167 | ## Best Practice #4 - Keep Router Guards Organized
168 |
169 | Here are a few tips to keep your router guards organized. These are just guidelines, but I have found them to be very helpful.
170 |
171 | ### Name Your Guards Well
172 |
173 | Guards should use the following naming convention:
174 |
175 | - File Name: `name.function.guard.ts`
176 | - Class Name: `NameFunctionGuard`
177 |
178 | Each part being identified as:
179 |
180 | - `name` - this is the name of your guard. What are you guarding against?
181 | - `function` - this is the function your guard will be attached to. Angular supports `CanActivate`, `CanActivateChild`, `CanDeactivate`, and `Resolve`.
182 |
183 | An example of an Auth Guard that is attached to the `CanActivate` function would be named as follows:
184 |
185 | - File Name: `auth.can-activate.guard`
186 | - Class Name: `AuthCanActivateGuard`
187 |
188 | ### Group under `_guards` folder
189 |
190 | Organize all top-level guards under a folder named `src/app/_guards`. I have seen apps dump guards in the top level directory and this is messy, especially if you end up with more than a few guards.
191 |
192 | ### Use Barrel Exports
193 |
194 | > The jury is still out on whether or not using barrel exports is officially considered a "best practice" or even supported by the Angular style guide. However, I am a big fan of the clean organization this provides. This method is offered as a suggestion.
195 |
196 | Make sure that `src/app/_guards` has a nice and clean `index.ts` barrel export. Barrel exports are simply `index.ts` files that group together and export all public files from a directory. An example is as follows:
197 |
198 | ```typescript
199 | export * from './auth.can-activate.guard';
200 | export * from './require-save.can-deactivate.guard';
201 | ```
202 |
203 | Without Barrel Exporting:
204 |
205 | ```typescript
206 | import { AuthCanActivateGuard } from 'src/app/_guards/auth.can-activate.guard';
207 | import { RequireSaveCanDeactivateGuard } from 'src/app/_guards/require-save.can-deactivate.guard';
208 | ```
209 |
210 | With Barrel Exporting:
211 |
212 | ```typescript
213 | import {
214 | AuthCanActivateGuard,
215 | RequireSaveCanDeactivateGuard
216 | } from 'src/app/_guards';
217 | ```
218 |
219 | An example application with a `_guards` directory would look as follows:
220 |
221 | 
222 |
223 | ### Organize Feature-Specific Route Guards
224 |
225 | If you have guards that are _only_ used in a particular `FeatureRoutes` array, then store these routes underneath a folder named `_guards` underneath your feature folder. Make sure to follow the same naming conventions defined above, as well as barrel exporting.
226 |
227 | - Place guards under a folder named `_guards` underneath your feature folder
228 | - Make sure to create a barrel export `index.ts` for clean importing
229 |
230 | An example feature directory with `_guards` would look as follows:
231 |
232 | 
233 |
234 | ## Finished Application Structure
235 |
236 | A completed application structure should look something like the following:
237 |
238 | 
239 |
240 | ---
241 |
242 | ## Example GitHub Repository
243 |
244 | I have created a demonstration repository on GitHub. Feel free to fork, clone, and submit PRs.
245 |
246 | [https://github.com/wesleygrimes/angular-routing-best-practices](https://github.com/wesleygrimes/angular-routing-best-practices)
247 |
248 | ## Conclusion
249 |
250 | It's important to remember that I have implemented these best practices in several "real world" applications. While I have found these best practices helpful, and maintainable, I do not believe they are an end-all be-all solution to organizing routes in projects; it's just what has worked for me. I am curious as to what you all think? Please feel free to offer any suggestions, tips, or best practices you've learned when building enterprise Angular applications with routing and I will update the article to reflect as such. Happy Coding!
251 |
--------------------------------------------------------------------------------
/angular.json:
--------------------------------------------------------------------------------
1 | {
2 | "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
3 | "version": 1,
4 | "newProjectRoot": "projects",
5 | "projects": {
6 | "angular-routing-best-practices": {
7 | "root": "",
8 | "sourceRoot": "src",
9 | "projectType": "application",
10 | "prefix": "app",
11 | "schematics": {},
12 | "architect": {
13 | "build": {
14 | "builder": "@angular-devkit/build-angular:browser",
15 | "options": {
16 | "outputPath": "dist/angular-routing-best-practices",
17 | "index": "src/index.html",
18 | "main": "src/main.ts",
19 | "polyfills": "src/polyfills.ts",
20 | "tsConfig": "src/tsconfig.app.json",
21 | "assets": [
22 | "src/favicon.ico",
23 | "src/assets"
24 | ],
25 | "styles": [
26 | "src/styles.css"
27 | ],
28 | "scripts": [],
29 | "es5BrowserSupport": true
30 | },
31 | "configurations": {
32 | "production": {
33 | "fileReplacements": [
34 | {
35 | "replace": "src/environments/environment.ts",
36 | "with": "src/environments/environment.prod.ts"
37 | }
38 | ],
39 | "optimization": true,
40 | "outputHashing": "all",
41 | "sourceMap": false,
42 | "extractCss": true,
43 | "namedChunks": false,
44 | "aot": true,
45 | "extractLicenses": true,
46 | "vendorChunk": false,
47 | "buildOptimizer": true,
48 | "budgets": [
49 | {
50 | "type": "initial",
51 | "maximumWarning": "2mb",
52 | "maximumError": "5mb"
53 | }
54 | ]
55 | }
56 | }
57 | },
58 | "serve": {
59 | "builder": "@angular-devkit/build-angular:dev-server",
60 | "options": {
61 | "browserTarget": "angular-routing-best-practices:build"
62 | },
63 | "configurations": {
64 | "production": {
65 | "browserTarget": "angular-routing-best-practices:build:production"
66 | }
67 | }
68 | },
69 | "extract-i18n": {
70 | "builder": "@angular-devkit/build-angular:extract-i18n",
71 | "options": {
72 | "browserTarget": "angular-routing-best-practices:build"
73 | }
74 | },
75 | "test": {
76 | "builder": "@angular-devkit/build-angular:karma",
77 | "options": {
78 | "main": "src/test.ts",
79 | "polyfills": "src/polyfills.ts",
80 | "tsConfig": "src/tsconfig.spec.json",
81 | "karmaConfig": "src/karma.conf.js",
82 | "styles": [
83 | "src/styles.css"
84 | ],
85 | "scripts": [],
86 | "assets": [
87 | "src/favicon.ico",
88 | "src/assets"
89 | ]
90 | }
91 | },
92 | "lint": {
93 | "builder": "@angular-devkit/build-angular:tslint",
94 | "options": {
95 | "tsConfig": [
96 | "src/tsconfig.app.json",
97 | "src/tsconfig.spec.json"
98 | ],
99 | "exclude": [
100 | "**/node_modules/**"
101 | ]
102 | }
103 | }
104 | }
105 | },
106 | "angular-routing-best-practices-e2e": {
107 | "root": "e2e/",
108 | "projectType": "application",
109 | "prefix": "",
110 | "architect": {
111 | "e2e": {
112 | "builder": "@angular-devkit/build-angular:protractor",
113 | "options": {
114 | "protractorConfig": "e2e/protractor.conf.js",
115 | "devServerTarget": "angular-routing-best-practices:serve"
116 | },
117 | "configurations": {
118 | "production": {
119 | "devServerTarget": "angular-routing-best-practices:serve:production"
120 | }
121 | }
122 | },
123 | "lint": {
124 | "builder": "@angular-devkit/build-angular:tslint",
125 | "options": {
126 | "tsConfig": "e2e/tsconfig.e2e.json",
127 | "exclude": [
128 | "**/node_modules/**"
129 | ]
130 | }
131 | }
132 | }
133 | }
134 | },
135 | "defaultProject": "angular-routing-best-practices"
136 | }
--------------------------------------------------------------------------------
/e2e/protractor.conf.js:
--------------------------------------------------------------------------------
1 | // Protractor configuration file, see link for more information
2 | // https://github.com/angular/protractor/blob/master/lib/config.ts
3 |
4 | const { SpecReporter } = require('jasmine-spec-reporter');
5 |
6 | exports.config = {
7 | allScriptsTimeout: 11000,
8 | specs: [
9 | './src/**/*.e2e-spec.ts'
10 | ],
11 | capabilities: {
12 | 'browserName': 'chrome'
13 | },
14 | directConnect: true,
15 | baseUrl: 'http://localhost:4200/',
16 | framework: 'jasmine',
17 | jasmineNodeOpts: {
18 | showColors: true,
19 | defaultTimeoutInterval: 30000,
20 | print: function() {}
21 | },
22 | onPrepare() {
23 | require('ts-node').register({
24 | project: require('path').join(__dirname, './tsconfig.e2e.json')
25 | });
26 | jasmine.getEnv().addReporter(new SpecReporter({ spec: { displayStacktrace: true } }));
27 | }
28 | };
--------------------------------------------------------------------------------
/e2e/src/app.e2e-spec.ts:
--------------------------------------------------------------------------------
1 | import { AppPage } from './app.po';
2 | import { browser, logging } from 'protractor';
3 |
4 | describe('workspace-project App', () => {
5 | let page: AppPage;
6 |
7 | beforeEach(() => {
8 | page = new AppPage();
9 | });
10 |
11 | it('should display welcome message', () => {
12 | page.navigateTo();
13 | expect(page.getTitleText()).toEqual('Welcome to angular-routing-best-practices!');
14 | });
15 |
16 | afterEach(async () => {
17 | // Assert that there are no errors emitted from the browser
18 | const logs = await browser.manage().logs().get(logging.Type.BROWSER);
19 | expect(logs).not.toContain(jasmine.objectContaining({
20 | level: logging.Level.SEVERE,
21 | } as logging.Entry));
22 | });
23 | });
24 |
--------------------------------------------------------------------------------
/e2e/src/app.po.ts:
--------------------------------------------------------------------------------
1 | import { browser, by, element } from 'protractor';
2 |
3 | export class AppPage {
4 | navigateTo() {
5 | return browser.get(browser.baseUrl) as Promise
9 | 2 | feature-one works! 3 |
4 | -------------------------------------------------------------------------------- /src/app/feature-one/feature-one.component.spec.ts: -------------------------------------------------------------------------------- 1 | import { async, ComponentFixture, TestBed } from '@angular/core/testing'; 2 | 3 | import { FeatureOneComponent } from './feature-one.component'; 4 | 5 | describe('FeatureOneComponent', () => { 6 | let component: FeatureOneComponent; 7 | let fixture: ComponentFixture2 | feature-two works! 3 |
4 | -------------------------------------------------------------------------------- /src/app/feature-two/feature-two.component.spec.ts: -------------------------------------------------------------------------------- 1 | import { async, ComponentFixture, TestBed } from '@angular/core/testing'; 2 | 3 | import { FeatureTwoComponent } from './feature-two.component'; 4 | 5 | describe('FeatureTwoComponent', () => { 6 | let component: FeatureTwoComponent; 7 | let fixture: ComponentFixture