DEV Community: Danny Koppenhagen

When Your Live Region Isn't Live: Fixing aria-live in Angular, React, and Vue

Danny Koppenhagen — Tue, 04 Nov 2025 22:11:03 +0000

You've built a modern single-page application with dynamic content alerts and live tickers - of course: with accessibility in mind. Therefore, you've added aria-live regions so screen reader users can hear what's changing. A success message here, a toast there. It should just work.

But when you test it with a screen reader… nothing. Silence. Your "live" region isn't so live after all.

If that sounds familiar, you're not alone. Accessibility professionals and framework developers alike run into this issue across Angular, Vue, React and other frameworks. The problem isn't your markup — it's how these frameworks manage the DOM.

Modern SPA frameworks do amazing things behind the scenes: they mount, unmount, and patch elements as state changes. Unfortunately, screen readers don't see your reactive data; they only notice actual DOM mutations. When the element holding your aria-live attribute is recreated or removed, assistive technologies lose track — and your updates are never announced.

In this post, we'll break down:

Why live regions may fail in your SPAs
The difference between polite and assertive announcements
What the aria-relevant and aria-atomic attributes actually doing
Two reliable solutions: local vs. global live regions
Concrete implementations in Angular, Vue, and React

By the end, you'll know how to make sure your live regions stay truly live — no matter what your framework is doing behind the scenes.

Understanding Why Live Region Breaks in SPAs

At its core, an aria-live region is easily explained:
it tells assistive technologies like screen readers,

"Hey, whenever this content changes, read it out loud."

That sounds straightforward — but modern frameworks make this promise surprisingly hard to keep.

When you update a variable in your app (like message = 'Saved!'), the screen reader doesn't care. It only reacts to changes in the actual DOM text inside an element that already has aria-live on it. If that element doesn't exist yet, or is about to be replaced, your announcement vanishes into thin air. In SPAs, it's common to show or hide UI elements conditionally:

<!-- Angular -->
@if (showMessage) {
<div aria-live="polite">{{ message }}</div>
}

<!-- Vue -->
<div v-if="showMessage" aria-live="polite">{{ message }}</div>

<!-- React -->
{showMessage && <div aria-live="polite">{message}</div>}

That looks fine — but when showMessage changes from false to true, the framework creates a brand new element in the DOM. From the screen reader's perspective, that's just a new element appearing, not an update in a live region it's been tracking. And since the text "Saved!" is already present when the node appears, the screen reader never gets a "text change" event — so it says nothing.

So, how can we fix it? To make aria-live work reliably, the element:

Must always exist in the DOM (no conditional rendering), and
Must have its text content changed dynamically, not replaced by a new node.

That's why we'll look at two approaches next:

Local live regions that stay mounted
A global announcer that's always present

But before that, let's clarify three critical ARIA attributes that often confuse developers: aria-live's politeness levels, and its lesser-known partners, aria-relevant and aria-atomic.

Understanding ARIA Attributes for dynamic announcements

Let's have a short look at the three Attributes aria-live, aria-relevant and aria-atomic and how they relate to each other.

Polite vs. Assertive — Choosing the Right "Voice"

The Attribute aria-live supports three "politeness" levels:

aria-live="off" (default) Disables live region announcements entirely. Use this to temporarily silence a region or explicitly mark static content.
aria-live="polite" Screen readers will wait until the user is idle before announcing changes. Use this for non-urgent updates — success toasts, progress updates, chat messages, etc.
aria-live="assertive" Screen readers will interrupt what they're currently reading to announce the change immediately. Use this sparingly, only for critical messages like errors or important alerts that require immediate attention.

Choosing between them is less about importance and more about urgency. Overusing assertive announcements can make your app feel chaotic or even hostile to users relying on assistive tech. A good rule of thumb:

Use polite for 90% of updates, assertive for things that truly can't wait, and off when you need to temporarily disable announcements or when your whole page is clearly only displaying live messages which the user is aware of.

`aria-relevant` — Controlling What Triggers an Announcement

The aria-relevant attribute refines what types of changes should be announced. It accepts values like additions, removals, text, or all. For most live regions, the default (aria-relevant="additions text") is ideal — it announces when new content is added or existing text changes.

However, if you have a region where elements are frequently added and removed (like a list of active users or temporary notifications), you might want to control what triggers announcements:

<!-- Only announce when items are added, ignore removals -->
<ul aria-live="polite" aria-relevant="additions">
  <li>User Alice joined</li>
  <li>User Bob joined</li>
  <!-- Announces "User Bob joined" when added, silent when removed -->
</ul>

You can also combine values for fine control:

<div aria-live="assertive" aria-relevant="additions removals text">Error occurred</div>

`aria-atomic` — Controlling How Much Gets Announced

The aria-atomic attribute determines whether the screen reader should announce only the changed part of a live region or the entire content.

aria-atomic="false" (default) Only announces the specific text that changed. Good for regions where you append new content (like chat messages or logs).
aria-atomic="true" Announces the entire content of the live region, even if only part of it changed. Essential for regions where the full context matters (like status messages or form validation summaries).

Consider this example:

<!-- Without aria-atomic (default: false) -->
<div aria-live="polite">
  <span>Items in cart: </span>
  <span>3</span> <!-- Only "3" gets announced when updated -->
</div>

<!-- With aria-atomic="true" -->
<div aria-live="polite" aria-atomic="true">
  <span>Items in cart: </span>
  <span>3</span> <!-- "Items in cart: 3" gets announced when updated -->
</div>

For most status messages and notifications, aria-atomic="true" provides better context.

For chat messages, you'd typically use aria-live="polite" with aria-atomic="false" so each new message is announced individually without interrupting the user:

<!-- Chat messages example -->
<div aria-live="polite" aria-atomic="false">
  <div>Alice: Hello!</div>
  <div>Bob: Hi there!</div>
  <!-- Only "Bob: Hi there!" gets announced when added -->
</div>

In short:

aria-live defines when to speak (or not at all with off)
aria-relevant defines what to speak
aria-atomic defines how much to speak

Together, they let you tune your live regions for exactly the right balance of awareness and calm.

The Two Main Solutions

Once you understand why aria-live fails in SPAs, the fix becomes much clearer. There are essentially two reliable strategies — and which one you choose depends on your use case.

Local Live Regions

If you only need to announce updates inside a specific component — say, a chat window, a progress indicator, or a status label — a local live region can work perfectly.

The trick is to make sure the element itself never leaves the DOM. Don't use v-if, @if(), or conditional JSX that destroys the node. Instead, keep it mounted and update its text content when something changes.

<!-- Angular -->
<div aria-live="polite" aria-relevant="text" [hidden]="!showMessage">{{ message }}</div>

<!-- Vue example -->
<div aria-live="polite" aria-relevant="text" v-show="showMessage">
  {{ statusMessage }}
</div>

<!-- React -->
<div aria-live="polite" aria-relevant="text" hidden={!showMessage}>{message}</div>

✅ Pros

Keeps announcements close to their visual context
Implementation on-site with minimal markup
Lightweight for component-specific updates
Works without global dependencies

⚠️ Cons

You must ensure the live region never unmounts
Tricky to coordinate if you have multiple regions in different places
Some screen readers struggle if too many live regions are active at once

Local live regions are great for self-contained components that are always rendered (like a chat transcript or a loading status). But for transient messages — like success toasts, error banners, or form confirmations — they're not ideal. That's where the second pattern shines.

Global Live Region

This is the most reliable and scalable approach. You create a single, persistent live region that stays mounted for your entire app's lifetime — usually at the root level — and expose a function or service to push messages into it.

Think of it like a message bus for screen readers.

<!-- template for your root component or index.html -->
<div id="aria-live-polite" aria-live="polite" aria-atomic="true" class="sr-only"></div>
<div id="aria-live-assertive" aria-live="assertive" aria-atomic="true" class="sr-only"></div>

To actually hide this live regions visually, you should use a common CSS implementation which makes it hidden but accessible and ensures screen readers will pick it up:

.sr-only:not(:focus):not(:active) {
  clip: rect(0 0 0 0);
  clip-path: inset(50%);
  height: 1px;
  overflow: hidden;
  position: absolute;
  white-space: nowrap;
  width: 1px;
}

Whenever you now need to announce something, you just call a helper:

announce('Form submitted successfully.');

Under the hood, it clears and rewrites the text content to trigger a DOM mutation:

const region = document.getElementById('aria-live-polite');
region.textContent = '';
setTimeout(() => (region.textContent = message), 50);

We will see that we don't have to do this by hand since there are very popular solutions for our frameworks already implementing this approach.

✅ Pros

Always present in the DOM and therefore extremely reliable
Works across routes and components
Centralized and easy to test
Handles polite vs. assertive globally

⚠️ Cons

Announcements lose some local context ("Where did that message come from?")
Requires a global setup or shared service

Implementing Reliable Live Regions in Angular, Vue, and React

Now let's see how to make them work in practice — using the global live announcer pattern, since it's the most robust option across all three frameworks.

Angular

Angular already ships an accessibility helper called LiveAnnouncer in the Angular CDK.

ng add @angular/cdk

Once you have installed the CDK (which I recommend since it also has other nice helpers for supporting accessibility), you can use the LiveAnnouncer as follows:

// save-button.ts
import { LiveAnnouncer } from '@angular/cdk/a11y';
import { Component, inject } from '@angular/core';

@Component({
  selector: 'app-save-button',
  template: `<button (click)="onSave()">Save</button>`
})
export class SaveButton {
  #liveAnnouncer = inject(LiveAnnouncer);

  onSave() {
    this.#liveAnnouncer.announce('Settings saved successfully.', 'polite');
  }
}

The CDK automatically creates a hidden live region and manages timing — no manual DOM work needed.

Vue 3

For Vue applications, I recommend using vue-a11y/vue-announcer.

npm install @vue-a11y/announcer@next # Vue 3
# OR:
npm install @vue-a11y/announcer      # Vue 2

Once installed, setup the VueAnnouncer for your App.

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

import VueAnnouncer from '@vue-a11y/announcer'
import '@vue-a11y/announcer/dist/style.css'

createApp(App)
  .use(VueAnnouncer)
  .use(router)
  .mount('#app');

After that, place the component containing the global live region(s) in your main component:

<!-- App.vue -->
<template>
  <VueAnnouncer class="sr-only" />
  ...
</template>

The last step is to use the composable useAnnouncer which pushes messages into the live region:

<!-- SaveButton.vue -->
<template>
  <button @click="onSave">Save</button>
</template>

<script setup>
import { useAnnouncer } from '@vue-a11y/announcer'

const { polite } = useAnnouncer()

function onSave() {
  polite('Settings saved successfully.')
}
</script>

React

For React, I recommend using @react-aria/live-announcer:

npm install @react-aria/live-announcer

After installation, you can call the announce function which will set up the global live region if not already present and push the message into it.

// SaveButton.tsx
import { announce } from '@react-aria/live-announcer';

function SaveButton() {
  const handleSave = () => {
    announce('Settings saved successfully.');
  };

  return <button onClick={handleSave}>Save</button>;
}

The library handles the DOM manipulation and timing automatically, making it a reliable choice for production apps.

Conclusion

Making aria-live work reliably in modern SPAs comes down to understanding how screen readers interact with the DOM. The core issue is that frameworks like Angular, Vue, and React often destroy and recreate elements, breaking the connection assistive technologies need to announce changes. By keeping live regions mounted and using established announcer services, you can ensure your dynamic content reaches all users effectively.

The root cause: Screen readers track DOM mutations, not reactive state — when elements are recreated, announcements may fail
Keep it stable: Live regions must stay mounted; update text content, not structure
Choose wisely: Use polite for most updates, assertive only for critical alerts
Two patterns: Local regions for persistent components, global announcers for transient messages
Use proven tools: Angular CDK's LiveAnnouncer, @vue-a11y/announcer for Vue, @react-aria/live-announcer for React
Test with real users: Screen reader behavior varies — always validate with actual assistive technology
The payoff: Reliable announcements make your app more inclusive, responsive, and trustworthy

Thanks for Ferdinand Malcher, Milan Wanielik and Maximilian Franzke for reviewing this article.
Cover image: Picture from Freepik, edited.

Route based navigation menus in Vue

Danny Koppenhagen — Mon, 19 Dec 2022 16:53:38 +0000

Recently while working on Vue app, I asked myself: Isn’t the main navigation menu somehow related to the configuration of the routes and routing tree? And can't it be built dynamically from the router configuration?

With this question in my mind, I started to work on a very simple but representative example of how to achieve this by enriching the route configuration using the meta option.

The following example allows you to easily wrap big parts of your app into a module that is self contained and only exposes a bit of route configuration which can be imported and included in the main router configuration.

The app has a simple navigation component that extracts all available routes provided by the Vue Router.
These routes have all the information needed by a navigation item to build a menu point and define the routing target.

The following picture shows an high level overview of the architecture.

TL;DR

You can check out the complete working example with the source code in the following Stackblitz project:

https://stackblitz.com/edit/vue3-dynamic-menu

basic app setup

Let's create a simple Vue project using Vue3 and Vue-Router.

npm init vue@latest
npm i vue-router@4

Setup the router

First we need the basic route configuration which represents the routing tree and in the end our menu structure.

We want to focus on the basic menu configuration and the initial page we are loading.
Therefore we will create the MainPage component which we can place in the src/components directory.
The component should simply display its name for demonstartion purpose:

<script setup lang="ts"></script>

<template>
  <div>MainPage.vue</div>
</template>

The next thing we want to do is to setup the route for this component.
Therefore we are creating the router.ts file within the src directory.
We are importing the MainPage component and using it for the route main.
Furthermore we are adding a redirect to "/main" when the root-route "/" is opened.
To be able to get the displayble menu label later, we add the meta object to the route configuration containing the label.

import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router';

import MainPage from './components/MainPage.vue';

export const routes: RouteRecordRaw[] = [
  //default route redirection
  { path: '/', redirect: { name: 'main' } },
  // common app routes
  {
    path: '/main',
    name: 'main',
    component: MainPage,
    meta: {
      label: 'Main Page',
    },
  }
];

export const router = createRouter({
  history: createWebHistory(),
  routes,
});

The exported router must now be used in the main.ts file:

import { createApp } from 'vue';
import './style.css';
import App from './App.vue';
import { getRouter } from './router';
import { routes } from './app-section-1/routes';

const app = createApp(App);

app.use(getRouter(routes));

app.mount('#app');

Now we have to add the <router-view /> to our App.vue file to be able to render the correct component routed by the Vue Router.

<script setup lang="ts"></script>

<template>
  <router-view />
</template>

Build the menu items based on route `meta`

So far so good: we’ve configured our first route so that we can later build a single menu item using the route configuration.

The next step is to create the navigation component (AppNav) that extracts the meta information from the route for the menu item and renders it. Therefore we have to filter for the occurrence of our provided meta data as we only want to display menu items that have a label configured in the meta information.

The result is an array of all relevant routes.
We iterate over the items with v-for and pass each element to a new component NavItem that takes a route configuration object for rendering a single navigation menu item.

<script setup lang="ts">
import { useRouter, useRoute } from 'vue-router';

import NavItem from './NavItem.vue';

const router = useRouter();
const filteredRoutes = router.options.routes.filter((r) => r.meta?.label);
</script>

<template>
  <nav>
    <ul>
      <NavItem
        v-for="(routeConfig, index) in filteredRoutes"
        :key="index"
        :route-config="routeConfig"
      />
    </ul>
  </nav>
</template>

Before we forget, let's add the AppNav component to our App component above the <router-view />:

<script setup lang="ts">
import AppNav from './components/AppNav.vue';
</script>

<template>
  <AppNav />
  <hr />
  <router-view />
</template>

Next, we are create the NavItem component.
We are defining a single prop which gets passed by the parent component called routeConfig which contains a whole route configuration record.
Now we can focus on the template.
Next add a <router-link> and pass the route target using the unique name.
For the label of the link we can use the label from our meta information object which we defined in the router configuration.

<script setup lang="ts">
import { computed } from 'vue';
import type { RouteRecordRaw } from 'vue-router';

const props = defineProps<{
  routeConfig: RouteRecordRaw;
}>();
</script>

<template>
  <li class="nav-item">
    <router-link :to="{ name: routeConfig.name }" aria-current-value="page">
      {{ routeConfig.meta.label }}
    </router-link>
  </li>
</template>

Great! The hardest part is now done (wasn't that tricky right?) and probably this solution already fit's for the majority.
However there are two things I would like to describe in advance, as they may be relevant for you:

How to make the navigation easily extensible
How to implement child menu items

Make the navigation extensible

Let's assume we have an extensible app where we outsource some pages and its child route configurations and make them includable in our app.
This could for example be relevent when adding complete menus and pages for specific users with appropriate permissions.

Therefore we want to make our route configuration extensible, so we can pass additional routes and child routes linked with their components to our router.

To do this, we simply wrap the exported route into a function that accepts a list of route configurations as a Rest parameter.

/* ... */
export function getConfiguredRouter(...pluginRoutes: RouteRecordRaw[][]) {
  return createRouter({
    history: createWebHistory(),
    routes: [...routes, ...pluginRoutes.flat()],
  });
}

Next we need to adjust our main.ts file.
We pass the result received from getConfiguredRouter() containing the additional routes we want to add.

/* ... */
import { getConfiguredRouter } from './router';
import { routes } from './app-section-1/routes';
/* ... */
app.use(getConfiguredRouter(routes));
/* ... */

Let's create a new folder app-section-1 simulating this kind of app plugin or modules containing the extensible part for our app.
Here we create another routes.ts file that holds the route configuration for this app part.

The configuration defines a base route that represents the main navigation item and redirects to its first child route page-1.
Here, we configure two child routes linked to their corresponding components which are created in the next step.

import type { RouteRecordRaw } from 'vue-router';

import Page1 from './components/Page1.vue';
import Page2 from './components/Page2.vue';

export const routes: RouteRecordRaw[] = [
  {
    path: '/app-section-1',
    name: 'appSection1',
    redirect: { name: 'appSection1Page1' },
    meta: { label: 'App Section 1' },
    children: [
      {
        path: 'page-1',
        name: 'appSection1Page1',
        component: Page1,
        meta: { label: 'Page 1' },
      },
      {
        path: 'page-2',
        name: 'appSection1Page2',
        component: Page2,
        meta: { label: 'Page 2' },
      },
    ],
  },
];

We are creating the components Page1 and Page2 wihtin the /src/app-section-1/components directory.

Their implementation follows the one of the MainPage component: They simply display their component names in the template for demo purposes.

Render child menu items

With the current version, we will already see both main navigation menu entries.
But as we configured child elements with labels, we also want to display them in the menu too.
Therefore we simply add the appropriate template in the NavItem component, as we already have everything we need by receiving the route configuration of the parent which contains all the information to render the child items.

<!-- ... -->
<template>
  <li class="nav-item">
    <router-link :to="{ name: routeConfig.name }">
      {{ routeConfig.meta.label }}
    </router-link>
    <ul v-if="routeConfig.children">
      <li
        class="child-item"
        v-for="(r, index) in routeConfig.children"
        :key="index"
      >
        <router-link :to="{ name: r.name }" aria-current-value="page">
          {{ r.meta.label }}
        </router-link>
      </li>
    </ul>
  </li>
</template>

Styling active links

To highlight the active menu items, we can now use the two automatically create CSS classes router-link-active and router-link-exact-active.

router-link-active: Matches when a part of the URL matches the target route path of the <router-link>
router-link-exact-active: Matches when the whole route in the URL matches the exact target route path of the <router-link>

a.router-link-active {
  background-color: lightblue;
}
a.router-link-exact-active {
  background-color: #f3aff8;
}

Conclusion

Passing meta information like label to the vue router configuration lets us easily build dynamic generated menus.
We no longer have to manually adjust our main navigation when adding new sites to our page as the menu is automatically extended by accessing the routes meta information.
This approach can reduce some template boilerplate.

You can use this approach to loosely couple whole parts of your app by adding them as separate modules without the need to add internals like the navigation titles to the main app part.

The whole working example can be seen in the following Stackblitz project:

https://stackblitz.com/edit/vue3-dynamic-menu

Thanks for Darren Cooper and Joachim Schirrmacher for reviewing this article.

Speed up your Angular schematics development with useful helper functions

Danny Koppenhagen — Mon, 14 Sep 2020 09:33:12 +0000

Speed up your Angular schematics development with useful helper functions

Angular CLI schematics offer us a way to add, scaffold and update app-related files and modules. However, there are some common things we will probably want integrate in our schematics: updating your package.json file, adding or removing an Angular module or updating component imports.

Currently, the way of authoring an Angular Schematic is documented on angular.io.
However, there is one big thing missing there: the way of integrating typical and repeating tasks.
The Angular CLI itself uses schematics for e.g. generating modules and components, adding imports or modifying the package.json file.
Under the hood each of the schematics uses some very common utils which are not yet documented but available for all developers anyway.
In the past, I've seen some Angular CLI Schematic projects where people were trying to implement almost the same common util methods on their own.
However, since some of these are already implemented in the Angular CLI, I want to show you some of those typical helpers that you can use for you Angular CLI Schematic project to prevent any pitfalls.

⚠️ Attention: not officially supported

The helper functions I present you in this article are neither documented nor officially supported, and they may change in the future.
Alan Agius, member of the Angular CLI core team replied in a related issue (#15335) for creating a public schematics API reference:

[...] those utils are not considered as part of the public API and might break without warning in any release.

So, there are plans to provide some utilities via a public API but this is still in the planning stage.
While things evolve, it's my intention to keep this article as up-to-date as possible.

The following Angular CLI schematics util functions are based on the Angular CLI version 12.0.0.

If you use these functions and they will break in the future, you can check out the source code changes for the utility functions and adjust your code.

🕹 Examples and playground on GitHub

To follow and try out the examples I present you in this article, I prepared a playground repository on GitHub.
Clone this repo and check out the README.md inside to get started with the playground. 🚀

Create an Angular schematics example project

First things first: We need a project where we can try things out.
You can either use an existing schematics project or simply create a new blank one:

npx @angular-devkit/schematics-cli blank --name=playground

If you are not familar with the basics of authoring schematics, I recommend you to read the Angular Docs and the blog post "Total Guide To Custom Angular schematics" by Tomas Trajan first as well as the article series "Angular Schematics from 0 to publishing your own library" by Natalia Venditto first.

After setting up the new blank project we should have this file available: src/playground/index.ts.

import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';

export function playground(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    console.log('schematic works');
    return tree;
  };
}

This is the base for the following examples and explanations.
Please make sure that you can execute the blank schematic by calling it on the console:

npx @angular-devkit/schematics-cli .:playground

or if you installed the schematics CLI globally via npm i @angular-devkit/schematics-cli:

schematics .:playground

The . refers to the current directory where our schematics project lives.

Check out the basic example in the playground repository on GitHub

Basic types

In case you are not familiar with the structure of schematics, I will just explain some very basic things shortly:

A Tree is the structured virtual representation of every file in the workspace which we apply the schematic to.
A Rule is called with a Tree and a SchematicContext. The Rule is supposed to make changes on the Tree and returns the adjusted Tree.
The SchematicContext contains information necessary for the schematics to execute some rules.

Install the helpers from `@schematics/angular`

A second thing we need to do is to install the package @schematics/angular which contains all the utils we need for the next steps.
This package contains all the schematics the Angular CLI uses by itself when running commands like ng generate or ng new etc.

npm i --save @schematics/angular

Changing the `package.json`: Get, Add and Remove (dev-, peer-) dependencies

A very common thing when authoring a schematic is adding a dependency to the package.json file.
Of course, we can implement a function that parses and writes to/from our JSON file.
But why should we solve a problem that's already solved?

For this, we can use the functions provided by @schematics/angular/utility/dependencies to handle dependency operations.
The function addPackageJsonDependency() allows us to add a dependency object of type NodeDependency to the package.json file.
The property type must contain a value of the NodeDependencyType enum.
Its values represent the different sections of a package.json file:

dependencies,
devDependencies,
peerDependencies and
optionalDependencies.

The first parameter to this util function is the Tree with all its files.
The function will not just append the dependency to the appropriate section, it will also insert the dependency at the right position, so that the dependencies list is ordered ascending by its keys.

We can use the getPackageJsonDependency() function to request the dependency configuration as a NodeDependency object.
The good thing here is: We don't need to know in which of the sections a dependency is located. It will look up the dependency in sections of the package.json file: dependencies, devDependencies, peerDependencies and optionalDependencies.

The third function I want to show is removePackageJsonDependency().
Just like getPackageJsonDependency(), it can be called with a Tree and the package name and it will remove this dependency from the package.json file.

By default, all these functions will use the package.json file in the root of the tree, but we can pass a third parameter containing a specific path to another package.json file.

Last but not least we don't want our users to manually run npm install on the console after adding dependencies.
Therefore, we can add a new NodePackageInstallTask via the addTask method on our context.

import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
import { NodePackageInstallTask } from '@angular-devkit/schematics/tasks';
import {
  NodeDependency,
  NodeDependencyType,
  getPackageJsonDependency,
  addPackageJsonDependency,
  removePackageJsonDependency,
} from '@schematics/angular/utility/dependencies';

export function playground(_options: any): Rule {
  return (tree: Tree, context: SchematicContext) => {
    const dep: NodeDependency = {
      type: NodeDependencyType.Dev,
      name: 'moment',
      version: '~2.27.0',
      overwrite: true,
    };

    addPackageJsonDependency(tree, dep);
    console.log(getPackageJsonDependency(tree, 'moment'))
    // { type: 'devDependencies', name: 'moment', version: '~2.27.0' }

    removePackageJsonDependency(tree, 'protractor');
    console.log(getPackageJsonDependency(tree, 'protractor'))
    // null

    context.addTask(new NodePackageInstallTask(), []);

    return tree;
  };
}

To really check that the NodePackageInstallTask is properly executed, you need to disable the schematics debug mode that's enabled by default during development and local execution:

schematics .:playground --debug=false

Add content on a specific position

Sometimes we need to change some contents of a file.
Independently of the type of a file, we can use the InsertChange class.
This class returns a change object which contains the content to be added and the position where the change is being inserted.

In the following example we will create a new file called my-file.extension with the content const a = 'foo'; inside the virtual tree.
First, we will instantiate a new InsertChange with the file path, the position where we want to add the change and finally the content we want to add.
The next step for us is to start the update process for the file using the beginUpdate() method on our tree.
This method returns an object of type UpdateRecorder.
We can now use the insertLeft() method and hand over the position and the content (toAdd) from the InsertChange.
The change is now marked but not proceeded yet.
To really update the file's content we need to call the commitUpdate() method on our tree with the exportRecorder.
When we now call tree.get(filePath) we can log the file's content and see that the change has been proceeded.
To delete a file inside the virtual tree, we can use the delete() method with the file path on the tree.

Let's have a look at an implementation example:

import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics/';
import { InsertChange } from '@schematics/angular/utility/change';

export function playground(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    const filePath = 'my-file.extension';
    tree.create(filePath, `const a = 'foo';`);

    // insert a new change
    const insertChange = new InsertChange(filePath, 16, '\nconst b = \'bar\';');
    const exportRecorder = tree.beginUpdate(filePath);
    exportRecorder.insertLeft(insertChange.pos, insertChange.toAdd);
    tree.commitUpdate(exportRecorder);
    console.log(tree.get(filePath)?.content.toString())
    // const a = 'foo';
    // const b = 'bar';

    tree.delete(filePath); // cleanup (if not running schematic in debug mode)
    return tree;
  };
}

Determine relative path to the project root

You might want to determine the relative path to your project root e.g. for using it in a template you want to apply in some location of your application.
To determine the correct relative import path string for the target, you can use the helper function relativePathToWorkspaceRoot().

import {
  Rule,
  SchematicContext,
  Tree,
  url,
  apply,
  template,
  mergeWith
} from '@angular-devkit/schematics/';
import { relativePathToWorkspaceRoot } from '@schematics/angular/utility/paths';

export function playground(_options: any): Rule {
  return (_tree: Tree, _context: SchematicContext) => {
    const nonRootPathDefinition = 'foo/bar/'; // "./foo/bar" | "foo/bar/" work also
    const rootPathDefinition = ''; // "." | "./" work also
    console.log(relativePathToWorkspaceRoot(nonRootPathDefinition));
    // "../.."
    console.log(relativePathToWorkspaceRoot(rootPathDefinition));
    // "."

    const sourceTemplates = url('./files');
    return mergeWith(
      apply(
        sourceTemplates, [
          template({
            relativePathToWorkspaceRoot: relativePathToWorkspaceRoot(nonRootPathDefinition),
          }),
        ]
      )
    );
  };
}

If you have e.g. a JSON file template in the directory files and you want to insert the path, you can use the helper function in the template as follows:

{
  "foo": "<%= relativePathToWorkspaceRoot %>/my-file-ref.json"
}

For more details about how to use and apply templates in your own schematics, check out the blog post by Tomas Trajan: "Total Guide To Custom Angular schematics" and the article series "Angular Schematics from 0 to publishing your own library" by Natalia Venditto.

Add TypeScript imports

In the previous section we learned how to add content to some file.
However, this way for changing a file isn't the best and only works well when we know the exact position where to add some content.
Now imagine a user changes the format of the file before: This would lead to problems with finding the correct file position.

In many cases we want to modify TypeScript files and insert code into them.
And indeed there are also lots of utils that will help us to manage such operations.

Imagine you want the schematic to import the class Bar in a specific file from the file bar.ts;
You could simply add the whole import line but there are edge cases:
What if the target file already contains an import or even a default import from bar.ts.
In that case we would have multiple import lines for bar.ts which causes problems.

Luckily there is another great helper that takes care of adding imports or updating existing ones.
The function insertImport() needs the source file to update and the path to the file followed by the import name and the file path for the import to be added.
The last parameter is optional – if set to true, the import will be added as a default import.

import * as ts from 'typescript';
import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics/';
import { insertImport } from '@schematics/angular/utility/ast-utils';
import { InsertChange } from '@schematics/angular/utility/change';

export function playground(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    const filePath = 'some-file.ts';
    const fileContent = `import { Foo } from 'foo';
const bar = 'bar;
`;
    tree.create(filePath, fileContent);
    const source = ts.createSourceFile(
      filePath,
      fileContent,
      ts.ScriptTarget.Latest,
      true
    );
    const updateRecorder = tree.beginUpdate(filePath);
    const change = insertImport(source, filePath, 'Bar', './bar', true);
    if (change instanceof InsertChange) {
      updateRecorder.insertRight(change.pos, change.toAdd);
    }
    tree.commitUpdate(updateRecorder);
    console.log(tree.get(filePath)?.content.toString())
    return tree;
  };
}

The example above will add the content import Bar from './bar'; right before the constant.
As we marked it as default import, the import name is not put in curly braces ({ }).

Update `NgModule`

Now we know how we can modify TypeScript imports using the util functions.
However, just importing something isn't enough in most cases.
There are common things like importing a component and adding it to the NgModule in the declarations array or inserting a module in the imports section.
Luckily, there are some helpers provided for these operations.
These function also based on the insertImport() function, so that they will handle existing file imports and just update the import lists accordingly.

Add a declaration to a module

The first thing I want to show you is how you can add a component to the declarations of an NgModule.
For this, let's assume you create a schematic that adds a new DashboardComponent to your project.
You don't need to add the import manually and then determine the right place to insert the component to the declarations of the NgModule.
Instead, you can use the addDeclarationToModule() function exported from @schematics/angular/utility/ast-utils.

In the following example we will create an AppModule from the moduleContent using ts.createSourceFile() first.
Then we will register the updateRecorder as learned in the examples before.
Now we call the addDeclarationToModule() function with the source file and the module path followed by the name of the component we want to import and the relative path to the module where we can find the component.
As a result it returns us an array of Change objects that contain the positions and the contents for the change.
Finally, we can handle these changes one-by-one by iterating over the array.
For all changes of type InsertChange we can now call the method updateRecorder.insertleft() with the position of the change and the content to be added.

import * as ts from 'typescript';
import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics/';
import { addDeclarationToModule } from '@schematics/angular/utility/ast-utils';
import { InsertChange } from '@schematics/angular/utility/change';

export function playground(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    const modulePath = 'app.module.ts';
    const moduleContent = `import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }
`;
    tree.create(modulePath, moduleContent);

    const source = ts.createSourceFile(
      modulePath,
      moduleContent,
      ts.ScriptTarget.Latest,
      true
    );
    const updateRecorder = tree.beginUpdate(modulePath);
    const changes = addDeclarationToModule(
      source,
      modulePath,
      'DashboardComponent',
      './dashboard.component'
    ) as InsertChange[];
    for (const change of changes) {
      if (change instanceof InsertChange) {
        updateRecorder.insertLeft(change.pos, change.toAdd);
      }
    }
    tree.commitUpdate(updateRecorder);
    console.log(tree.get(modulePath)?.content.toString())

    return tree;
  };
}

When we execute this schematic now, we can see in the log that the following import line has been added to the file:

/* ... */
import { DashboardComponent } from './dashboard.component';

@NgModule({
  declarations: [
    AppComponent,
    DashboardComponent
  ],
  /* ... */
})
export class AppModule { }

`NgModule`: add `imports`, `exports`, `providers`, and `bootstrap`

Similar to the previous example we can re-export something we imported by using the addExportToModule() function and adding an import to the NgModule by using addImportToModule().
We can also modify the providers, and bootstrap arrays by using addProviderToModule() and addBootstrapToModule().
Again, it will take care of all the things necessary such as extending and creating imports, checking for existing entries in the NgModule metadata and much more.

/* ... */
import {
  addImportToModule,
  addExportToModule,
  addProviderToModule,
  addBootstrapToModule
} from '@schematics/angular/utility/ast-utils';
/* ... */

export function playground(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    /* ... */
    const exportChanges = addExportToModule(
      source,
      modulePath,
      'FooModule',
      './foo.module'
    ) as InsertChange[];
    const importChanges = addImportToModule(
      source,
      modulePath,
      'BarModule',
      './bar.module'
    ) as InsertChange[];
    const providerChanges = addProviderToModule(
      source,
      modulePath,
      'MyProvider',
      './my-provider.ts'
    ) as InsertChange[];
    const bootstrapChanges = addBootstrapToModule(
      source,
      modulePath,
      'MyComponent',
      './my.component.ts'
    ) as  InsertChange[];
    /* ... */
    console.log(tree.get(modulePath)?.content.toString())
    return tree;
  };
}

Our result will now look like this:

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
import { FooModule } from './foo.module';
import { BarModule } from './bar.module';
import { MyProvider } from './my-provider.ts';
import { MyComponent } from './my.component.ts';
import { BazComponent } from './baz.component.ts';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    BarModule
  ],
  providers: [MyProvider],
  bootstrap: [MyComponent],
  exports: [FooModule]
})
export class AppModule { }

Add route declarations

Let's have a look at another common scenario: We want our schematic to insert a route definition to a module that calls RouterModule.forRoot() or .forChild() with a route definition array.
For this, we can use the helper function addRouteDeclarationToModule() which returns a Change object which we need to handle as an InsertChange.

import * as ts from 'typescript';
import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics/';
import { addRouteDeclarationToModule } from '@schematics/angular/utility/ast-utils';
import { InsertChange } from '@schematics/angular/utility/change';

export function playground(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    const modulePath = 'my-routing.module.ts';
    const moduleContent = `import { NgModule } from '@angular/core';

    const myRoutes = [
      { path: 'foo', component: FooComponent }
    ];

    @NgModule({
      imports: [
        RouterModule.forChild(myRoutes)
      ],
    })
    export class MyRoutingModule { }
`;
    tree.create(modulePath, moduleContent);

    const source = ts.createSourceFile(
      modulePath,
      moduleContent,
      ts.ScriptTarget.Latest,
      true
    );
    const updateRecorder = tree.beginUpdate(modulePath);
    const change = addRouteDeclarationToModule(
      source,
      './src/app',
      `{ path: 'bar', component: BarComponent }`
    ) as InsertChange;
    updateRecorder.insertLeft(change.pos, change.toAdd);
    tree.commitUpdate(updateRecorder);
    console.log(tree.get(modulePath)?.content.toString())

    return tree;
  };
}

The example above will insert the route definition object { path: 'bar', component: BarComponent } into the myRoutes array by finding the variable associated in forRoot() or forChild().

Retrieve the Angular workspace configuration

Each Angular app lives in an Angular workspace containing an angular.json configuration file.
If we want to get either the path to the workspace configuration file or the configuration from the file itself, we can use the getWorkspacePath() and getWorkspace() functions by passing in the current Tree object.

import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
import { getWorkspacePath, getWorkspace } from '@schematics/angular/utility/config';

export function playground(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    // returns the path to the Angular configuration file
    // ('/angular.json' or probably `.angular.json` for older Angular projects)
    console.log(getWorkspacePath(tree));

    // returns the whole configuration object from the 'angular.json' file
    console.log(JSON.stringify(getWorkspace(tree), null, 2));
  };
}

To try out things locally, we need to execute the schematics from an Angular app root path on our system.
To do so, navigate into an existing Angular app or create a new one for testing purposes.
Then, execute the schematic from there by using the relative path to the src/collection.json file and adding the schematic name after the colon (:).

ng new some-test-project --routing  # create a new test project
cd some-test-project      # be sure to be in the root of the angular project
# assume the schematics project itself is located relatively to the angular project in '../playground'
schematics ../playground/src/collection.json:playground # execute the 'playground' schematic

Get default path for an app inside the workspace

An Angular workspace can contain multiple applications or libraries.
To find their appropriate main paths, you can use the helper function createDefaultPath().
We need to pass in the Tree object and the name of the app or library we want to get the path for.

import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
import { createDefaultPath } from '@schematics/angular/utility/workspace';

export function playground(_options: any): Rule {
  return async (tree: Tree, _context: SchematicContext) => {
    const defaultPath = await createDefaultPath(tree, 'my-lib');
    console.log(defaultPath); // '/projects/my-lib/src/lib'
  };
}

Let's create a new library inside our testing Angular app called my-lib, to try it out:

ng g lib my-lib  # create a new library inside the Angular workspace
# assume the schematics project itself is located relatively to the angular project in '../playground'
schematics ../playground/src/collection.json:playground # execute the 'playground' schematic

Call schematics from schematics

If you run a schematic, you may come to the point where one schematic should execute another one.
For example: You create schematics for generating a specific component.
You also develop a ng add or ng new schematic to set up things for you and create an example component by default.
In such cases you may want to combine multiple schematics.

Run local schematics using the `RunSchematicTask`

First we want to use the RunSchematicTask class to achieve our goal.
Let's say we have a collection file like the following:

{
  "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json",
  "schematics": {
    "ng-add": {
      "description": "Demo that calls the 'playground' schematic inside",
      "factory": "./ng-add/index#ngAdd"
    },
    "playground": {
      "description": "An example schematic.",
      "factory": "./playground/index#playground"
    }
  }
}

The factory for ng-add is located in src/ng-add/index.ts.
Then inside this schematic we can call a new RunSchematicTask with the name of the schematic we want to execute and the project name from the Angular workspace.
To really execute the operation we need to pass the task to the context.

import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
import { RunSchematicTask } from '@angular-devkit/schematics/tasks';

export function ngAdd(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    context.addTask(
      new RunSchematicTask('playground', { project: 'test-workspace' })
    );
    return tree;
  };
}

To check if it works we can fill our playground (src/playground/index.ts) schematic as follows and log the call:

import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';

export function playground(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    console.log('schematic \'playground\' called');
    return tree;
  };
}

If we now run schematics ../playground/src/collection.json:ng-add --debug=false from our example Angular project, we can see that the ng-add schematic has called the playground schematic.

With this knowledge you can define small atomic schematics that can be executed "standalone" or from another Schematic that combines multiple standalone schematics and calls them with specific parameters.

Check out the example in the playground repository on GitHub

Run schematics by using the `schematic()` and `externalSchematic()` function

Perfect, we can now execute and combine our schematics.
But what if we want to combine external schematics developed by others and integrate them in our own schematics?
Users are lazy, so we don't want to leave it up to them to manually execute some other things before running our schematics.

Imagine you are working in a big company with multiple different Angular projects.
This company already has its own standardized UI library, but all the applications are very different and ran by different teams (so not really a use case for a Monorepo).
However, there are also things they all have in common like a Single Sign-On.
Also, the basic design always looks similar – at least the header and the footer of all the apps.

I've often seen companies building a reference implementation for such apps that's then cloned / copied and adjusted by all developers.
However, there are some problems with this kind of workflow:

You always have to keep the reference project up-to-date.
You have to clean up your copy of the project from stuff you don't need.
You need to tell all teams to copy this reference to keep track of changes and to adjust their copies frequently.

Thus, a better solution in my opinion is to use schematics for the whole integration and upgrade workflow.
You can create an ng new schematic that will scaffold the whole project code for you.
But you don't want to start from scratch, so you probably want to combine things like these:

ng add: Add your schematics to an existing project
- Corporate UI library (always)
- Single Sign-On (optional)
- Header Component (optional)
- Footer Component (optional)
ng new: Create a new project with your company defaults
- Create the basic application generated by the Angular CLI (externalSchematic)
- Run the ng add Schematic

Alright, we already know how we can achieve most of these things.
However, there's one thing we haven't learned yet: How to run other (external) schematics?
We can use the externalSchematic function for this.

But first things first, let's check if our collection file is ready to start:

{
  "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json",
  "schematics": {
    "ng-add": {
      "description": "Call other schematics from the same or other packages",
      "factory": "./ng-add/index#playground"
    },
    "ng-new": {
      "description": "Execute `ng new` with predefined options and run other stuff",
      "factory": "./ng-new/index#playground"
    }
  }
}

Using the special Schematic names ng-add and ng-new let's you later use the schematic by just executing ng add/ng new (instead of other schematics called with ng generate).
There is also a special Schematic named ng-update which will be called in the end with the ng update Angular CLI command.

After we defined the schema, we can now start to implement our schematics.
To execute an external Schematic, it must be available in the scope of the project..
However, since we want to create a completely new project with the ng new Schematic, we don't have any node_modules installed in the target directory where we want to initialize the Angular workspace.
To run an external command we can use the spawn method from child_process (available globally for Node.js).
This creates a new process that executes a command (in our case: npm install @schematics/angular).
To make things look synchronous we wrap the method call into a Promise and await for the Promise to be resolved.
Now we listen to the close event from spawn and check that there was no error during install (code equals 0).
If everything worked fine, we will resolve the Promise, otherwise we can throw an error.
The last step is to chain all of our Rules:
We first use the externalSchematic() function to run the ng new Schematic from Angular itself and set up the basic app.
We will hand over some default options here such a using SCSS, support legacy browsers, strict mode, etc.
Angulars ng new schematic requires also, that we define the specific version for their schematic to be used.
In our case we want to use the ng new schematic from the Angular CLI version 12.0.0.
The second call is our ng add Schematic that adds our company specific components, UI libs and so on to the project.

We've already learned how to run a local Schematic by using the RunSchematicTask class that we need to add to our context object.
In this example we are using the schematic() function to achieve the same goal.
Why are there two ways? To be honest: I actually don't know.
I found both implementations in the source code of Angular CLI.

import {
  Rule,
  SchematicContext,
  Tree,
  externalSchematic,
  schematic,
  chain
} from '@angular-devkit/schematics';
import {
  Schema as AngularNgNewSchema,
  PackageManager,
  Style
} from '@schematics/angular/ng-new/schema';
import { spawn } from 'child_process';

export function playground(options: AngularNgNewSchema): Rule {
  return async (_tree: Tree, _context: SchematicContext) => {
    const angularSchematicsPackage = '@schematics/angular';
    const ngNewOptions: AngularNgNewSchema = {
      version: '12.0.0',
      name: options.name,
      routing: true,
      strict: true,
      legacyBrowsers: true,
      style: Style.Scss,
      packageManager: PackageManager.Npm
    }
    await new Promise<boolean>((resolve) => {
      console.log('📦 Installing packages...');
      spawn('npm', ['install', angularSchematicsPackage])
        .on('close', (code: number) => {
          if (code === 0) {
            console.log('📦 Packages installed successfully ✅');
            resolve(true);
          } else {
            throw new Error(
              `❌ install Angular schematics from '${angularSchematicsPackage}' failed`
            );
          }
        });
    });
    return chain([
      externalSchematic(angularSchematicsPackage, 'ng-new', ngNewOptions),
      schematic('ng-add', {})
    ]);
  };
}

When we now run the ng new Schematic from somewhere outside an Angular workspace, we can see that first of all the Angular ng new Schematic is executed with our predefined settings.
After this, the ng add schematics is called.

schematics ./playground/src/collection.json:ng-new --debug=false
📦 Installing packages...
📦 Packages installed successfully ✅
? What name would you like to use for the new workspace and initial project? my-project
CREATE my-project/README.md (1027 bytes)
CREATE my-project/.editorconfig (274 bytes)
CREATE my-project/.gitignore (631 bytes)
CREATE my-project/angular.json (3812 bytes)
...
CREATE my-project/src/app/app.component.scss (0 bytes)
CREATE my-project/src/app/app.component.html (25757 bytes)
CREATE my-project/src/app/app.component.spec.ts (1069 bytes)
CREATE my-project/src/app/app.component.ts (215 bytes)
CREATE my-project/src/app/package.json (816 bytes)
CREATE my-project/e2e/protractor.conf.js (869 bytes)
CREATE my-project/e2e/tsconfig.json (294 bytes)
CREATE my-project/e2e/src/app.e2e-spec.ts (643 bytes)
CREATE my-project/e2e/src/app.po.ts (301 bytes)
⠏ Installing packages...
✔ Packages installed successfully.
schematic works

After you have deployed the Schematic, you can now execute it by running:

npm i -g my-schematic-package-name # install the Schematic so it's available globally
ng new my-app --collection=my-schematic-package-name # Run the Angular CLI's `ng new` Schematic with the defined collection

Similar to this example you can call the ng add Schematic from the collection if you are in an existing Angular workspace:

ng add my-schematic-package-name

Check out the example in the playground repository on GitHub

Conclusion

The presented util functions are great and comfortable helpers you can use to create your own Angular CLI schematics.
However, as they aren't officially published until now, you should keep track of any changes by keeping an eye on the documentation issue (#15335) and changes on the related code.

Summary

Function	Description
`getPackageJsonDependency()`	Get a package configuration from the `package.json` (dev-, peer-, optional-) dependencies config.
`addPackageJsonDependency()`	Add a NPM package to the `package.json` as (dev-, peer-, optional-) dependency.
`removePackageJsonDependency()`	Remove a NPM package from the `package.json` (dev-, peer-, optional-) dependencies.
`relativePathToWorkspaceRoot()`	Get the relative import path to the root of the workspace for a given file inside the workspace.
`insertImport()`	Insert an import statement for a file to an existing TypeScript file.
`addDeclarationToModule()`	Import a declaration (e.g. Component or Directive) and add it to the `declarations` array of an Angular module.
`addImportToModule()`	Import an Angular Module and add it to the `imports` array of another Angular module.
`addExportToModule()`	Import an Angular Module and add it to the `exports` array of another Angular module.
`addProviderToModule()`	Import a service / provider and add it to the `providers` array of an Angular module.
`addBootstrapToModule()`	Import a Component and add it to the `bootstrap` array of an Angular module.
`addRouteDeclarationToModule()`	Add a route definition to the router configuration in an Angular routing module.
`getWorkspacePath()`	Retrieve the path to the Angular workspace configuration file (`angular.json`).
`getWorkspace()`	Get the configuration object from the Angular workspace configuration file (`angular.json`)
`createDefaultPath()`	Get the default application / library path for a project inside an Angular workspace.

Class	Description
`InsertChange`	This class returns a change object with the content to be added and the position where a change is being inserted.
`NodePackageInstallTask`	A task instance that will perform a `npm install` once instantiated and added to the `context` via `addTask()`.
`RunSchematicTask`	A task that runs another schematic after instantiation and adding it to the `context` via `addTask()`.

Thank you

Special thanks goes to Minko Gechev, Tomas Trajan and Ferdinand Malcher for the feedback and revising this article.

My Development Setup

Danny Koppenhagen — Thu, 27 Aug 2020 18:21:18 +0000

My Development Setup

In the following article I will present you what tools I am using during my day-to-day development workflow.
Also, I will show you a list of extensions and their purpose that will help me and probably you too being more productive.

Introduction

As a developer I always give my best to be productive, to write good and well documented source code and to share my knowledge.
For all this, I use great tools and extensions that will help me to get the most of it and working faster and cleaner.
Those tools and extensions help me during my everyday life as a developer for:

Development of Angular, Vue.js apps,
sharing knowledge with recordings, GIFs, screenshots, code snippets etc.,
writing good documentation, and
being more productive in general.

Both at work and in my free time I am working on an Apple MacBook Pro.
But most of the tools and software listed here is available for Windows, macOS and Linux distributions.

Software

Let's get started with some basic software that I use.

Tabby / iTerm2

The default Terminal app for macOS fulfills its purpose but for being more productive I can recommend the alternative terminal applications Tabby and iTerm2.

I used iTerm2 for a long time and it's a great tool with lots of configuration options.
You can create tabs, use profiles and customize styles and layouts.

However, a few weeks ago I switched from iTerm2 to Tabby (formerly Terminus).
Tabby is a quite new terminal app and it's Open Source!
Behind the scenes it's an Electron App using Angular.
You can also customize it a lot.
A feature I like particularly is that you can define SSH and Serial Port profiles.
You can then later activate those profiles so that you can access an SSH remote host or a serial port without entering anything manually in the terminal.

Cakebrew – macOS only

If you are on a Mac, you probably know Homebrew – the package manager for macOS.
If you don't know Homebrew: You should definitely check it out.
Personally I prefer to install most of my Software via Homebrew as I can easily manage updates later without having to manually download the packages.
However, since I don't remember all Homebrew commands all the time and to get an overview of the installed packages, I use a Homebrew GUI called CakeBrew.
This lets me easily update and manage my installed Homebrew packages.

NVM

Working on multiple projects requires sometimes different environments.
As a web developer Node.js is essential and should always be up-to-date but sometimes you need to use different versions of Node.js and NPM for different projects.
NVM (Node Version Manager) let's you easily install and switch between multiple Node.js Versions.
My recommendation is also to check-in the .nvmrc file in every project to help other team members to use the right version of Node.js automatically.

Fork

As a developer, version control with Git is essential for your development workflow.
Personally I do all of the basic operations via the command line, like creating commits, adding files to the staging area, pulling and pushing.
However, there are some things where I prefer to use a GUI for assistance:

graphical overview of commits and branches (history)
interactive rebase
managing multiple remote repositories

Fork is a very nice, clean and powerful Git GUI that helps you to control Git in an easy and interactive way.

Visual Studio Code

In the last years, Microsoft has improved its free IDE Visual Studio Code a lot, and with every frequent release it gets even more powerful.
One of the things that makes VSCode such a great IDE is the wide range of available extensions and plugins.
VSCode is a very universal and adoptable IDE which has great support and tools for lots of programming languages.
So it doesn't matter if you develop a web application, a mobile app using e.g. Flutter, a C# or a Python app: You can use VSCode for all of that and you don't need to get start using a new specific IDE for each and every specific language.

Later in this article, I will present you a list of my favorite extensions for VSCode.

Chrome

As a web developer, a modern browser like Google Chrome is essential.
In my opinion the developer and debugging tools are more mature compared to Firefox.
Chrome is also very up-to-date in terms of the latest JavaScript features and it has a wide range of extensions you can install that will help you to even be more productive developing web applications.

A list of my favorite extensions for Google Chrome can be found further down in this article.

Insomnia

Insomnia is a great and simple tools that's very easy to use when you want to interact with REST or GraphQL endpoints. It has a very simple UI but it's powerful nonetheless.
You can call endpoints, check their responses and also create batch requests or save your requests for using them later again.
I personally prefer Insomnia over Postman which I used before and which is also very powerful.
However, in my opinion the UI of Postman got a bit confusing during the last years by introducing new features.

draw.io

From time to time as a developer you need to illustrate things and flows.
For this, I mostly use draw.io. It's available as a web application but also as an installable desktop version.
Draw.io provides a lot of basic icons and vector graphics for network illustrations, UML, diagrams, engineering icons for circuits and much more.

RecordIt

When I develop extensions for VSCode or other tools I always give my best to present users how to use these tools.
The best way to present things is in a visual way as a screenshot or a GIF / video screencast.
This supplements the textual description and thus, can be processed more easily by users.
RecordIt lets you record your screen and create small screencasts that can be shared via a simple URL as a video or GIF.

KeyCastr

Recording screencasts can be supplemented by displaying the keys you are pressing during the recording.
This is a great way to present keyboard shortcuts without having to manually explain which keys you're using.
For that purpose I use the tool KeyCastr.

Visual Studio Code Extensions

Since Visual Studio Code Version 1.48.0 the Feature Settings Sync became stable and available for everyone.
This feature allows you to sync your settings between different installations of VSCode using your Microsoft or GitHub account.
When you've installed VSCode on multiple machines and you always want to have the instances in sync, you should definitely set up this feature.

The next part is all about the VSCode extensions I am using so let's walk quickly over the plugins I've installed on my VSCode instances:

Appearance


	Bracket Pair Colorizer 2 This tool will colorize opening and closing brackets in different colors, so you get a better overview in your code. Note: Visual Studio Code now includes native support for bracket pair colorization which is way faster than using the extension.
	Color Highlight After installing this extension it will highlight all valid web color values with their appropriate color so that you can directly see the color.
	Image Preview After installing this plugin, you will see a little preview image right next to your code line number when a source code line contains a valid image file path.
	Indented Block Highlighting This extensions highlights the intented area that contains the cursor.
	Indent Rainbow This plugin colorizes the different indentation levels. This is especially helpful when writing YAML files or Python applications where the indentations play an important role for the code semantics.
	Log File Highlighter If you ever have to investigate a bunch of log files you will love this plugin. It highlights log information like the severity or timestamps so it will be easier for you to inspect them.
	Peacock Peacock is great when you are working with multiple VSCode windows at the same time. You can simply colorize them to quickly find out which project is currently open.
	Rainbow CSV This extension will colorize each column in a CSV file in a different color, so you can better read the file contents.
	TODO Highlight This extension will highlight `TODO`, `FIXME` and some other annotations within comments in your code.

Docs


	AsciiDoc The AsciiDoc Plugin gives you syntax highlighting, a preview and snippets for the AsciiDoc format.
	Code Review This is an extension I wrote by myself. It allows you to create expert reviews / code reviews for a workspace that can be exported as a formatted HTML report or importable CSV/JSON file. This extension is pretty helpful if you are doing for example one-time code reviews for customers or probably students but you don't have direct access to a Gitlab or GitHub repository where you can directly add comments in a merge/pull request.
	emojisense I personally like using emojis and I use them in `README.md` files for my open source projects at GitHub. However, one thing I always have to look up are the emjoykey for the supported GitHub emojis. With this extension I have an autocompletion and I can search for them.
	File Tree to Text Generator An extension I created by myself: It lets you generate file / directory trees for Markdown, LaTeX, ASCII or even a custom format right from your VSCode file explorer.
	Markdown Preview Mermaid support Have you ever visualized things in your `README.md` file? Thanks to Mermaid.js you can easily create beautiful flowcharts, sequence diagrams and more. This plugin enables the preview support in VSCode for mermaid diagrams embedded in your markdown files.
	Markdown All in One This extension enables some great helpful features when writing Markdown files such as table of contents generation, auto-formatting the document and it gives you a great autocompletion feature.

Graphics


	Draw.io Integration This extension integrates the draw.io editor in VSCode. You can directly edit draw.io associated files.
	SVG This extension will give you SVG code highlight and preview support. You can even export the SVG directly from the preview as a `*.png` graphic.

JavaScript / TypeScript


	ESLint This extensions detects your ESLint configuration for code conventions and displays the violations. Furthermore, it offers you to quick fix detected violations against some rules.
	Import Cost With this plugin installed, projects using webpack will be analyzed for their imports and the bundle size they will have. The resulting size is displayed right next to the import. This helps you to identify very big imported libs.
	JavaScript (ES6) code snippets This extension brings some great snippets for JavaScript / TypeScript like a short snippet `clg` for writing `console.log()` or `imp` for `import <foo> from '<foo>';`.
	Jest The Jest extension gives you auto completion and color indicators for successful / failing Jest tests.
	JS Refactor This extension gives you a lot of JavaScript refactoring utilities like convert to arrow function or rename variable.
	LintLens With this extension, metadata and usage information for ESLint rules will be displayed beside each rule.
	npm This extension let's you run your NPM scripts right from your `package.json` file.
	Sort JSON Objects With this extension you can simply right click on a JSON object and sort the items inside.
	TSLint This extension enables TSLint support for linting TypeScript files in VSCode.
	Visual Studio IntelliCode Installing this extension will give you an even better IntelliSense which is AI-assisted.
	Version Lens With Version Lens you can directly see the currently installed and the latest versions of a package in your `package.json` file.

HTML/Handlebars/CSS/SASS/SCSS/LESS


	CSS Peak With this extension you can see and edit your CSS definitions from a related stylesheet directly from your HTML files.
	IntelliSense for CSS class names in HTML This plugin gives you auto suggestions for CSS class names in your HTML templates.
	Web Accessibility Using this plugin helps you to find accessibility violations in your markup and displays hints for WAI-ARIA best practices.
	stylelint Lint CSS/SCSS/SASS/Less Style definitions

Angular


	Arrr Arrr is a great extension for the Angular Framework. It lets you easily refactor code and for example mark some lines in the template and move it into a child component.
	Angular Language Service When you are developing an Angular app, this extension is essential: It gives you quick info, autocompletion and diagnostic information.
	Angular Follow Selector This extensions allows you to click on Angular selectors in the template and get redirected to their definition in the component.

Vue.js


	Vetur Vetur gives you tooling for Vue.js development.
	Vue Peak This extension gives you Go To Definition and Peek Definition support for Vue components.

Handlebars


	Handlebars This extension provides you with code snippets for Handlebars files as well as with syntax highlighting.
	Handlebars Preview With the Handlebars Preview extension you can put a JSON file right next to your Handlebars template and the plugin will inject the data into the template to display a preview of how it would look like.

Git


	Git Temporal Git Temporal is a great plugin for interactively searching in your git history based on a timeline. You can even mark ranges on a timeline to see all the changes in between the chosen time range.
	GitLens Show the authorship of code lines right next to them. This can help you a lot if you may not understand some part of the code: just check out who created it and ask for support.

Other


	Auto Correct You may be like me and there are some words you'll always spell wrong or you making the same typo all the time. One of my common mistakes is to write `seperate` instead of `separate`. With this plugin you can define such words or patterns that will be automatically replaced with the correctly spelled word.
	Code Spell Checker With this extension your code is checked for common typos and such unknown words will be highlighted as you may know it from Microsoft Word or other text editor software.
	DotENV This extensions highlights the configuration in `.env` files
	Excel Viewer If you open and edit CSV or Excel files from VSCode, you will probably need this extension. This allows you to display the data in a formatted table that you can sort and filter.
	Debugger for Chrome This debugger extensions allows you to debug your JavaScript code in the Google Chrome browser from your code editor.
	Docker The Docker extension easily lets you create, manage, and debug your applications containerized with Docker. It also gives you IntelliSense for your related Docker configuration files.
	EditorConfig This plugin will check your workspace for an EditorConfig configuration file and applies these settings to your workspace.
	Live Server With the Live Server extension you can open an HTML file in the browser and the server watches for changes and refreshes the Browser preview.
	Nx Console This plugin gives you a UI for Nx Monorepos and the Nx CLI.
	Path Intellisense This plugin brings you autocompletion for filenames.
	Polacode With Polacode you can mark code lines and create screenshots from the selection. This is great for e.g. presentations or sharing stuff on Twitter.
	Prettier Prettier is – in my opinion – the best code formatter especially when working with JavaScript / TypeScript. The extension for Prettier will allow you to set up Prettier as default formatter for VSCode or just for specific programming languages. `{ "editor.defaultFormatter": "esbenp.prettier-vscode", "[javascript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" } }`
	Regexp Explain Running this extension will let you explore regular expressions visually in a realtime preivew editor
	Visual Studio Code Commitizen Support This plugin adds a command panel for creating Conventional Commits with support.
	vsc-nvm Automatically use the right Node.js version form the NVM.
	YAML This extension gives you a comprehensive YAML language support.
	Zeplin If you work with Zeplin, this official plugin provides you with quick access to your designs.

Google Chrome Extensions

Google Chrome is great and it already brings a lot of possibilities that help developers to improve their web apps.
However, there are some really great plugins I am using that I can recommend:


	Angular DevTools A must have addon for all Angular Developers that will help you profile and debug and optimize your Angular app.
	Aqua Buddy Stay hydrated by using Aqua Buddy! It will notify you to drink some water frequently.
	Axe Axe helps you to improve the grade of accessibility of your site.
	Chrome Capture This extension lets you record and share screenshots, videos and GIFs from a website.
	Chrome Regex Search Ever wanted to search on a site for more complex expressions? With this extension you can search a sites content by entering regular expressions.
	Export Selective Bookmarks This extensions lets you select specific directories and bookmarks from all your bookmarks to export them. Perfect if you want to help colleagues to onboard in your team or project.
	JSON Viewer Awesome This extension will automatically detect and format JSON files once you open them by calling the URL.
	Lighthouse Lighthouse analyzes your site for performance, accessibility and other common things and gives you a site score as well as some useful information how to improve your site.
	Pesticide Activating these extension lets you outline all elements on a site so that you can easier analyze paddings, margins and borders.
	Web Developer With this extension you will get a toolbox for website manipulation and testing tools. You can e.g. easily disable JavaScript or styles to see how your site behaves.

Scripts and other tools

Dotfiles

Personally, I like to keep my Mac up-to-date and therefore I will install most of my software via the Homebrew package manager.
Also, to be more efficient I use the oh-my-zsh framework for managing my shell configuration.
Most of my configurations is also published in my GitHub repository called .dotfiles.

Exclude all `node_modules` from TimeMachine backups (macOS only)

One thing I learned during my career is: backup, backup, backup.
It's better to have one more backup than data loss.
Fortunately, on a macOS system it's possible to set up Apple's TimeMachine for creating continuous system backups.
However, backing up everything takes a lot of time and there are things you don't need to back up like directories syncing with a cloud provider like Dropbox, Sharepoint, etc.
Those directories can easily be excluded from the TimeMachine backup by configuration.
This will keep the backups smaller and also in case of a restore, the system ready to use after a much shorter time.
But what about node_modules directories?
For sure: You can exclude them in the same way, but this is very sophisticated and you always need to remember this step once you create a new project.
Therefore, I am using a simple script.
It looks for all node_modules directories in my development directory (~/dev in my case) and excludes them from the backup:

#!/bin/bash
# exclude all `node_modules` folders within the dev directory
find "$HOME/dev" -name 'node_modules' -prune -type d -exec tmutil addexclusion {} \; -exec tmutil isexcluded {} \;
echo "Done. The excluded files won't be part of a time machine backup anymore."

To be sure the script updates the list of excluded directories frequently, I added a cronjob:

crontab -e

The actual cronjob config is the following:

0 12 * * *  cd $HOME/dev/.dotfiles && ./time-machine-excludes.sh # every day at 12:00

Feedback

Now as you know my dev setup, it's your turn! Is there any great tool or plugin you can recommend?
Then just contact me via E-Mail or Twitter and let me know!

Thank you

Special thanks goes to Ferdinand Malcher for revising this article.

Photo by Todd Quackenbush on Unsplash

Dig deeper into static site generation with Scully and use the most out of it

Danny Koppenhagen — Mon, 02 Mar 2020 19:14:51 +0000

Dig deeper into static site generation with Scully and use the most out of it

If you haven't heard about Scully yet, you should first check out my introduction article about it: »Create powerful fast pre-rendered Angular Apps using Scully static site generator«.

In my last blog post I gave you a short introduction to Scully and how to easily set up a very simple blogging website that is server-side rendered and ready to be shipped for production.
In the following article I will introduce some more advanced things you can do with Scully.
You will learn how you can setup a custom Markdown module or even use Asciidoc instead of Markdown.
I will guide you through the process of how to handle protected routes using a custom route plugin.

This blog post is based on versions:
@scullyio/ng-lib: 1.1.1
@scullyio/init: 1.1.4
@scullyio/scully: 1.1.1

Generate a post with a meta data template

As we already created our blogging site using Scully, we want to fill it with content now.
We already learned how we can use the @scullyio/init:post schematic to easily generate a new blog post.
Often posts do not only need the content, but also some meta information like thumbnail or author.
This meta information can be processed by the ScullyRouteService and it will be converted to JSON.
It can be quite handy to always remember to add such information right after creating a new post.
To make things easier we can specify a YAML template file with the meta information that will always be added when creating a new blog post using the schematic, like the following one:

description: <fill in a short description for the overview page>
published: false
author:
  name: Danny Koppenhagen
  mail: mail@k9n.dev
updated: dd.mm.yyyy
keywords:
  - Angular
language: en
thumbnail: assets/images/default.jpg

We can use the template when calling the @scullyio/init:post schematic:

ng g @scullyio/init:post --name="a new post" --meta-data-file=meta.yml

When we check our blog directory now we will see that the schematic added our YAML template to the meta data section of the newly created post file a-new-post.md.

If you have trouble remembering to add the meta-data-file option, just add a script to your package.json without the name option.
When you call the script using npm run <script-name> you will be prompted to input the file name.

Generate a custom Markdown module

Let's assume we want to add another module to our blogging website.
We want to have a projects section in our site that lists some information about current projects we are working on.
Like for our blog section, we want to easily write our content using Markdown.
To do so, we can use the @scullyio/init:markdown schematic:

ng g @scullyio/init:markdown --name=projects --slug=projectId --sourceDir=projects --route=projects

Let's have a look at the options we set:

name: This is the base name for the generated Angular module that Scully created for us.
slug: Here we define the placeholder name for the URL that will be filled with the basename of the Markdown files.
sourceDir: That's where we will store our Markdown files whose content is rendered by the Scully Markdown file plugin.
route: This is the name for the route before the :slug in the URLs where we can see our rendered content later.

Good to know: Under the hood the @scullyio/init:blog schematic just calls @scullyio/init:markdown with default options set. So in fact it's just a shortcut.

The basic things we need for our projects page are now available.
Let's have a look at it and see if it's working:

npm run build                   # Angular build
npm run scully -- --scanRoutes  # generate static build and force checking new routes
npm run scully serve            # serve the scully results

The `AsciiDoc` File Handler Plugin

Scully provides another File Handler Plugin out-of-the-box: The AsciiDoc plugin.
When you want to put the generated post files in a specific directory (not blog), you can define this via the target option.

ng g @scullyio/init:post --name="asciidoc example" --target=projects

The generated file will be a Markdown file initially.
Let's change the file extension, rename it to *.adoc and add a bit of content after it has been generated:

:title: 2020-01-21-projects
:description: blog description
:published: false

= 2020-01-21-projects

Let's show some source code!

.index.html
[#src-listing]
[source,html]
----
<div>
  <span>Hello World!</span>
</div>
----

And finally we build our project again and see if it works:

npm run build                   # Angular build
npm run scully -- --scanRoutes  # generate static build and force checking new routes
npm run scully serve            # serve the scully results

Great, as we can see: AsciiDoc files will be rendered as well out-of-the-box.

You can also define your own File Handler Plugin for other content formats.
Check out the official docs for it to see how it works.

Protect your routes with a custom plugin

Let's assume we have a protected section at our site that should only be visible for specific users.
For sure we can secure this space using an Angular Route Guard that checks if we have the correct permissions to see the pages.

Scully will by default try to identify all available app routes.
In fact it will also try to visit the protected pages and pre-render the result.
When Scully tries to do this, the Angular route guard kicks in and redirects us to an error or login page.
The page shown after the redirect is the page Scully will see and render.
This default behaviour is pretty okay, as Scully won't expose any protected information by creating static content from the protected data.
However, on the other hand, we don't want to pre-render such pages at all, so we need a way to tell Scully what pages to exclude from the rendering.
Another scenario you can imagine is when a page displays a prompt or a confirm dialog.
When Scully tries to render such pages it runs into a timeout and cannot render the page:

...
Puppeteer error while rendering "/secure" TimeoutError: Navigation timeout of 30000 ms exceeded

To prevent Scully from rendering specific pages we can simply create a custom plugin that will skip some routes.

To do so, we will create a new directory extraPlugin with the file skip.js inside:

const { registerPlugin, log, yellow } = require('@scullyio/scully');

function skipPlugin(route, config = {}) {
  log(`Skip Route "${yellow(route)}"`);
  return Promise.resolve([]);
}

const validator = async conf => [];
registerPlugin('router', 'skip', skipPlugin, validator);
module.exports.skipPlugin = skipPlugin;

We will import the function registerPlugin() which will register a new router plugin called skip.
The last parameter is the plugin function skipPlugin() that will return a promise resolving the routes.
It receives the route and options for the route that should be handled.
We will simply return an empty array as we won't proceed routes handled by the plugin.
We can use the exported log() function from Scully to log the action in a nice way.

Last but not least we will use the skip plugin in our scully.scully-blog.config.ts configuration file and tell the plugin which routes to handle:

import { ScullyConfig } from '@scullyio/scully';

require('./extraPlugin/skip');

export const config: ScullyConfig = {
  // ...
  routes: {
    // ...
    '/secure': { type: 'skip' },
  }
};

Checking the plugin by running npm run scully will output us the following result:

 ☺   new Angular build imported
 ☺   Started servers in background
Finding all routes in application.
...
Skip Route "/secure"
...

Perfect! As you can see the route is ignored by Scully now.

You can have a look at a more detailed example in my scully-blog-example repository.

Conclusion

In this follow-up article you learned how to add a custom Markdown module to Scully and how you can use the AsciiDoc plugin for rendering adoc files.
What is more, you can now handle protected routes by using a custom Scully route plugin.

Thank you

Special thanks go to Jorge Cano from the Scully core team and Ferdinand Malcher for revising this article.

Create powerful fast pre-rendered Angular Apps using Scully static site generator

Danny Koppenhagen — Wed, 01 Jan 2020 17:12:44 +0000

Create powerful fast pre-rendered Angular Apps using Scully static site generator

You probably heard of the JAMStack. It's a new way of building websites and apps via static site generators that deliver better performance and higher security. There have been tools for many platforms, but surprisingly not yet for Angular. These times are finally over. With this blog post, I want to show you how you can easily create an Angular blogging app by to pre-render your complete app.

On Dec 16, 2019 the static site generator Scully for Angular was presented.
Scully automatically detects all app routes and creates static sites out of it that are ready to ship for production.
This blog post is based on versions of Angular and Scully:
"@angular/core": "~13.0.0",
"@angular/cli": "~13.0.3",
"@scullyio/init": "^2.0.5",
"@scullyio/ng-lib": "^2.0.0",
"@scullyio/scully": "^2.0.0",
"@scullyio/scully-plugin-puppeteer": "^2.0.0",

About Scully

Scully is a static site generator (SSG) for Angular apps.
It analyses a compiled Angular app and detects all the routes of the app.
It will then call every route it found, visit the page in the browser, renders the page and finally put the static rendered page to the file system.
This process is also known as pre-rendering – but with a new approach.
The result compiled and pre-rendered app ready for shipping to your web server.

Good to know: Scully does not use Angular Universal for the pre-rendering.
It uses a Chromium browser to visit and check all routes it found.

All pre-rendered pages contain just plain HTML and CSS.
In fact, when deploying it, a user will be able to instantly access all routes and see the content with almost no delay.
The resulting sites are very small static sites (just a few KBs) so that even the access from a mobile device with a very low bandwidth is pretty fast.
It's significantly faster compared to the hundreds of KBs that you are downloading when calling a “normal” Angular app on initial load.

But that’s not all: Once the pre-rendered page is shipped to the user, Scully loads and bootstraps the “real” Angular app in the background on top of the existing view.
In fact Scully will unite two great things:
The power of pre-rendering and very fast access to sites and the power of a fully functional Single Page Application (SPA) written in Angular.

Get started

The first thing we have to do is to set up our Angular app.
As Scully detects the content from the routes, we need to configure the Angular router as well.
Therefore, we add the appropriate flag --routing (we can also choose this option when the CLI prompts us).

npx -p @angular/cli ng new scully-blog --routing # create an angular workspace
cd scully-blog  # navigate into the project

The next step is to set up our static site generator Scully.
Therefore, we are using the provided Angular schematic:

ng add @scullyio/init  # add Scully to the project

Et voilà here it is: We now have a very minimalistic Angular app that uses the power of Scully to automatically find all app routes, visit them and generate static pages out of them.
It's ready for us to preview.
Let's try it out by building our site and running Scully.

npm run build     # build our Angular app
npx scully        # let Scully run over our app and build it
npx scully serve  # serve the scully results

Scully will run only once by default. To let Scully run and watch for file changes, just add the --watch option (npx scully --watch).

After Scully has checked our app, it will add the generated static assets to our dist/static directory by default.
Let's quickly compare the result generated from Scully with the result from the initial Angular build (dist/scully-blog):

dist/
┣ scully-blog/
┃ ┣ assets/
┃ ┣ ...
┃ ┗ styles.ef46db3751d8e999.css
┗ static/
  ┣ assets/
  ┃ ┗ scully-routes.json
  ┣ ...
  ┗ styles.ef46db3751d8e999.css

If we take a look at it, except of the file scully-routes.json, that contains the configured routes used by Scully, we don't see any differences between the two builds.
This is because currently we only have the root route configured, and no further content was created.

Nonetheless, when running npx scully serve or npx scully --watch we can check out the result by visiting the following URL: localhost:1668.
This server serves the static generated pages from the dist/static directory like a normal web server (e.g. nginx or apache).

The `ScullyLibModule`

You may have realized, that after running the Scully schematic, the ScullyLibModule has been added to your AppComponent:

// ...
import { ScullyLibModule } from '@scullyio/ng-lib';

@NgModule({
  // ...
  imports: [
    // ...
    ScullyLibModule
  ]
})
export class AppModule { }

This module is used by Scully to hook into the angular router and to determine once the page Scully tries to enter is fully loaded and ready to be rendered by using the IdleMonitorService from Scully internally.
If we remove the import of the module, Scully will still work, but it takes much longer to render your site as it will use a timeout for accessing the pages.
So in that case even if a page has been fully loaded, Scully would wait until the timer is expired.

Turn it into a blog

Let’s go a bit further and turn our site into a simple blog that will render our blog posts from separate Markdown documents.
Scully brings this feature out of the box, and it’s very easy to set it up:

ng g @scullyio/init:blog                      # setup up the `BlogModule` and related sources
ng g @scullyio/init:post --name="First post"  # create a new blog post

After these two steps we can see that Scully has now added the blog directory to our project root.
Here we can find the markdown files for creating the blog posts — one file for each post.
We now have two files there: The initially created example file from Scully and this one we created with ng g @scullyio/init:post.

Let's go further

Now that we've got Scully installed and working, let's modify our Angular app to look more like an actual blog, and not just like the default Angular app.
Therefore, we want to get rid of the Angular auto generated content in the AppComponent first.
We can simply delete all the content of app.component.html except of the router-outlet:

<router-outlet></router-outlet>

Let’s run the build again and have a look at the results.
Scully assumes by default the route configuration hasn't changed meanwhile, and it can happen that it's not detecting the new bog entry we just created.
To be sure it will re-scan the routes, we will pass through the parameter --scan:

npm run build       # Angular build
npx scully --scan   # generate static build and force checking new routes
npx scully serve    # serve the scully results

When checking out our dist/static directory we can see that there are new subdirectories for the routes of our static blogging sites.
But what's that: When we will check the directory dist/static/blog/, we see somewhat like this:

blog/
┣ ___UNPUBLISHED___k9pg4tmo_2DDScsUiieFlld4R2FwvnJHEBJXcgulw
  ┗ index.html

This feels strange, doesn't it?
But Checking the content of the file index.html inside will tell us it contains actually the content of the just created blog post.
This is by intention: This Scully schematic created the markdown file with a meta flag called published that is by default set to false.
The internally used renderer plugin from Scully will handle this flag, and it creates an unguessable name for the route.
This allows us to create blog post drafts that we can already publish and share by using the link for example to let someone else review the article.
You can also use this route if you don't care about the route name.
But normally you would just like to change the metadata in the Markdown file to:

published: true

After this, run the build process again and the files index.html in dist/static/blog/<post-name>/ contain now our static pages ready to be served.
When we are visiting the route path /blog/first-post we can see the content of our markdown source file blog/first-post.md is rendered as HTML.

If you want to prove that the page is actually really pre-rendered, just disable JavaScript by using your Chrome Developer Tools.
You can reload the page and see that the content is still displayed.
Awesome, isn't it?

When JavaScript is enabled, Scully configures your static sites in that way, that you will see initially the static content.
In the background it will bootstrap your Angular app, and refresh the content with it.
You won't see anything flickering.

Hold on a minute! 😳

You may have realized: We haven’t written one line of code manually yet, and we have already a fully functional blogging site that’s server site rendered. Isn’t that cool?
Setting up an Angular based blog has never been easier.

Good to know: Scully also detects new routes we are adding manually to our app, and it will create static sites for all those pages.

Use the `ScullyRoutesService`

We want to take the next step.
Now we want to list an overview of all existing blog posts we have and link to their sites in our AppComponent.
Therefore, we can easily inject the ScullyRoutesService.
It will return us a list of all routes Scully found with the parsed information as a ScullyRoute array within the available$ observable.
We can easily inject the service and display the information as a list in our AppComponent.

import { Component } from '@angular/core';
import { ScullyRoutesService, ScullyRoute } from '@scullyio/ng-lib';
import { Observable } from 'rxjs';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  links$: Observable<ScullyRoute[]> = this.scully.available$;

  constructor(private scully: ScullyRoutesService) {}
}

To display the results, we can simply use ngFor with the async pipe and list the results.
A ScullyRoute will give us the routing path inside the route key and all other markdown metadata inside their appropriate key names.
So we can extend for example our markdown metadata block with more keys (e.g. thumbnail: assets/thumb.jpg) and we can access them via those (blog.thumbnail in our case).
We can extend app.component.html like this:

<ul>
  <li *ngFor="let link of links$ | async">
    <a [routerLink]="link.route">{{ link.title }}</a>
  </li>
</ul>

<hr />

<router-outlet></router-outlet>

This will give us a fully routed blog page:

The ScullyRoutesService contains all the available routes in your app.
In fact, any route that we add to our Angular app will be detected by Scully and made available via the ScullyRoutesService.available$ observable.
To list only blog posts from the blog route and directory we can just filter the result:

/* ... */
import { map, Observable } from 'rxjs';
/* ... */
export class AppComponent {
  links$: Observable<ScullyRoute[]> = this.scully.available$.pipe(
    map(routeList => {
      return routeList.filter((route: ScullyRoute) =>
        route.route.startsWith(`/blog/`),
      );
    })
  );

  constructor(private scully: ScullyRoutesService) {}
}

Wow! That was easy, wasn’t it?
Now you just need to add a bit of styling and content and your blog is ready for getting visited.

Fetch dynamic information from an API

As you may have realized: Scully needs a data source to fetch all dynamic routes in an app.
In case of our blog example Scully uses the :slug router parameter as a placeholder.
Scully will fill this placeholder with appropriate content to visit and pre-render the site.
The content for the placeholder comes in our blog example from the files in the /blog directory.
This has been configured from the schematics we ran before in the file scully.scully-blog.config.ts:

import { ScullyConfig } from '@scullyio/scully';

/** this loads the default render plugin, remove when switching to something else. */
import '@scullyio/scully-plugin-puppeteer';

export const config: ScullyConfig = {
  projectRoot: "./src",
  projectName: "scully-blog",
  outDir: './dist/static',
  routes: {
    '/blog/:slug': {
      type: 'contentFolder',
      slug: {
        folder: "./blog"
      }
    },
  }
};

I would like to show a second example.
Imagine we want to display information about books from an external API.
So our app needs another route called /books/:isbn.
To visit this route and pre-render it, we need a way to fill the isbn parameter.
Luckily Scully helps us with this too.
We can configure Router Plugin that will call an API, fetch the data from it and pluck the isbn from the array of results to fill it in the router parameter.

In the following example we will use the public service BookMonkey API (we provide this service for the readers of our German Angular book) as an API to fetch a list of books:

/* ... */

export const config: ScullyConfig = {
  /* ... */
  routes: {
    /* ... */
    '/books/:isbn': {
      'type': 'json',
      'isbn': {
        'url': 'https://api3.angular-buch.com/books',
        'property': 'isbn'
      }
    }
  }
};

The result from the API will have this shape:

[
  {
    "title": "Angular",
    "subtitle": "Grundlagen, fortgeschrittene Themen und Best Practices – mit NativeScript und NgRx",
    "isbn": "9783864906466",
    // ...
  },
  {
    "title": "Angular",
    "subtitle": "Grundlagen, fortgeschrittene Techniken und Best Practices mit TypeScript - ab Angular 4, inklusive NativeScript und Redux",
    "isbn": "9783864903571",
    // ...
  },
  // ...
]

After Scully plucks the ISBN, it will just iterate over the final array: ['9783864906466', '9783864903571'].
In fact, when running Scully using npx scully, it will visit the following routes, after we have configured the route /books/:isbn in the Angular router (otherwise non-used routes will be skipped).

/books/9783864906466
/books/9783864903571

We can see the result in the log:

enable reload on port 2667
 ☺   new Angular build imported
 ☺   Started servers in background
--------------------------------------------------
Watching blog for change.
--------------------------------------------------
 ☺   new Angular build imported
Finding all routes in application.
Using stored unhandled routes
Pull in data to create additional routes.
Finding files in folder "/<path>/blog"
Route list created in files:
  "/<path>/src/assets/scully-routes.json",
  "/<path>/dist/static/assets/scully-routes.json",
  "/<path>/dist/scully-blog/assets/scully-routes.json"

Route "/books/9783864903571" rendered into file: "/<path>/dist/static/books/9783864903571/index.html"
Route "/books/9783864906466" rendered into file: "/<path>/dist/static/books/9783864906466/index.html"
Route "/blog/12-27-2019-blog" rendered into file: "/<path>/dist/static/blog/12-27-2019-blog/index.html"
Route "/blog/first-post" rendered into file: "/<path>/dist/static/blog/first-post/index.html"
Route "/" rendered into file: "/<path>/dist/static/index.html"

Generating took 3.3 seconds for 7 pages:
  That is 2.12 pages per second,
  or 473 milliseconds for each page.

  Finding routes in the angular app took 0 milliseconds
  Pulling in route-data took 26 milliseconds
  Rendering the pages took 2.58 seconds

This is great. We have efficiently pre-rendered normal dynamic content!
And that was it for today.
With the shown examples, it's possible to create a full-fledged website with Scully.

Did you know that this blogpost and the overall website you are right now reading has also been created using Scully?
Feel free to check out the sources at:
github.com/d-koppenhagen/k9n.dev

If you want to follow all the development steps in detail, check out my provided Github repository
scully-blog-example.

Conclusion

Scully is an awesome tool if you need a pre-rendered Angular SPA where all routes can be accessed immediately without loading the whole app at once.
This is a great benefit for users as they don’t need to wait until the bunch of JavaScript has been downloaded to their devices.
Visitors and search engines have instantly access to the sites' information.
Furthermore, Scully offers a way to create very easily a blog and renders all posts written in Markdown.
It will handle and pre-render dynamic routes by fetching API data from placeholders and visiting every route filled by this placeholder.

Compared to "classic" pre-rending by using Angular Universal, Scully is much easier to use, and it doesn't require you to write a specific flavor of Angular.
Also, Scully can easily pre-render hybrid Angular apps or Angular apps with plugins like jQuery in comparison to Angular Universal.
If you want to compare Scully with Angular Universal in detail, check out the blog post from Sam Vloeberghs: Scully or Angular Universal, what is the difference?

If you want to dig a bit deeper into the features Scully offers, check out my second article.

Thank you

Special thanks go to Aaron Frost (Frosty ⛄️) from the Scully core team, Ferdinand Malcher and Johannes Hoppe for revising this article.

DEV Community: Danny Koppenhagen

When Your Live Region Isn't Live: Fixing aria-live in Angular, React, and Vue

Understanding Why Live Region Breaks in SPAs

Understanding ARIA Attributes for dynamic announcements

Polite vs. Assertive — Choosing the Right "Voice"

aria-relevant — Controlling What Triggers an Announcement

aria-atomic — Controlling How Much Gets Announced

The Two Main Solutions

Local Live Regions

Global Live Region

Implementing Reliable Live Regions in Angular, Vue, and React

Angular

Vue 3

React

Conclusion

Route based navigation menus in Vue

TL;DR

basic app setup

Setup the router

Build the menu items based on route meta

Make the navigation extensible

Render child menu items

Styling active links

Conclusion

Speed up your Angular schematics development with useful helper functions

Speed up your Angular schematics development with useful helper functions

⚠️ Attention: not officially supported

🕹 Examples and playground on GitHub

Create an Angular schematics example project

Basic types

Install the helpers from @schematics/angular

Changing the package.json: Get, Add and Remove (dev-, peer-) dependencies

Add content on a specific position

Determine relative path to the project root

Add TypeScript imports

Update NgModule

Add a declaration to a module

NgModule: add imports, exports, providers, and bootstrap

Add route declarations

Retrieve the Angular workspace configuration

Get default path for an app inside the workspace

Call schematics from schematics

Run local schematics using the RunSchematicTask

Run schematics by using the schematic() and externalSchematic() function

Conclusion

Summary

My Development Setup

My Development Setup

Introduction

Software

Tabby / iTerm2

Cakebrew – macOS only

Visual Studio Code Extensions

Appearance

Docs

Graphics

JavaScript / TypeScript

HTML/Handlebars/CSS/SASS/SCSS/LESS

Angular

Vue.js

Handlebars

Git

Other

Google Chrome Extensions

Scripts and other tools

Dotfiles

Exclude all node_modules from TimeMachine backups (macOS only)

Feedback

Dig deeper into static site generation with Scully and use the most out of it

Dig deeper into static site generation with Scully and use the most out of it

Generate a post with a meta data template

Generate a custom Markdown module

The AsciiDoc File Handler Plugin

Protect your routes with a custom plugin

Conclusion

Create powerful fast pre-rendered Angular Apps using Scully static site generator

Create powerful fast pre-rendered Angular Apps using Scully static site generator

About Scully

Get started

The ScullyLibModule

`aria-relevant` — Controlling What Triggers an Announcement

`aria-atomic` — Controlling How Much Gets Announced

Build the menu items based on route `meta`

Install the helpers from `@schematics/angular`

Changing the `package.json`: Get, Add and Remove (dev-, peer-) dependencies

Update `NgModule`

`NgModule`: add `imports`, `exports`, `providers`, and `bootstrap`

Run local schematics using the `RunSchematicTask`

Run schematics by using the `schematic()` and `externalSchematic()` function

Exclude all `node_modules` from TimeMachine backups (macOS only)

The `AsciiDoc` File Handler Plugin

The `ScullyLibModule`

Use the `ScullyRoutesService`