Notes on Migrating Angular Project to Nx Workspace & Angular v12 & Github Pages

https://unsplash.com/photos/hq96V-dazC4

It’s been a while that I touched the portfolio website. Hence, today I decided to level up the project and take advantage of better technology along the way. Here are the reasons behind the changes:

• Monorepos architect that can easily be extended and managed
• Angular Lazyload module -> more projects will not affects the existing performance.
• Fast deployment & build process + CI / CD support
• Shared libraries, models & services between projects
• JavaScript developer-friendly
• More

Without further ado, this is the process of migrating an existing Angular project to Nx Workspace & Angular v12 & deploy it to Github Pages

Upgrading existing Angular to the latest version (Angular v12 — at the time of writing this article)

I tried to follow the Nx Workspace and hope that by running one line of code can migrate the existing project to the Nx workspace, but it doesn’t happen :(

So I have to follow the manual migration process. I don’t want to migrate then update the existing to the latest version of Angular. It’s better to upgrade first then do the migration.

You can check the Angular Update Guide for migration. However, just run this line and it will tell what to do.

ng update

Migrating to Nx Workspace

After upgrading to the latest version of Angular, it’s time for migrating to Nx Workspace. It’s best practice to create another branch to test the manual process, so it won’t mess with your current branch.

git checkout -b nx 

If you are lucky, this command with help to transform an Angular CLI workspace to an Nx workspace.

ng add @nrwl/workspace

If you are not lucky — like me, you can always follow the manual process.

Step 1: Move the existing folder to a temp folder

All you need is the src folder, the other files can be deleted if you don’t need them.

Step 2: Generate a branch new Nx Workspace

npx create-nx-workspace myorg --preset=angular --linter eslint

When prompted for the application name, enter the project name from your current angular.json file.

Step 3: Copy over application files

Your application code is self-contained within the src folder of your Angular CLI workspace.

• Copy the src folder from your Angular CLI project to the apps/<app name> folder, overwriting the existing src folder.
• Copy any project-specific files, such as browserslist, or service worker configuration files into their relative path under the apps/<app name> folder.
• Transfer the assets, scripts, styles, and build-specific configuration, such as service worker configuration, from your Angular CLI angular.json to the Nx workspace angular.json file.

Step 4: Run and Test the New Project

Verify your app runs correctly by running:

ng serve <app name>

Then continue to check your testing & linting. Make sure everything is working fine. If it’s not, please follow the Nx Instruction.

Configure Github Actions for Deploying Project to Github Pages

I already set up the CI/CD for Github Actions. With the structure, I have to make some changes in order to adapt to the new destination output. Now my app will be located at:

dist/apps/<app-name>

Here is the YAML file for Github Actions

# .github/workflows/ci.yaml
name: Pull request or push to Dev Branch
on:
  push:
    branches:
      - dev
jobs:
  build-and-deploy:
    timeout-minutes: 30
    name: Deploy website and sentry
    runs-on: ubuntu-latest
steps:
      - name: Checkout
        uses: actions/checkout@v1
- uses: actions/setup-node@v1
        with:
          node-version: '14.x'
- uses: actions/cache@v2
        with:
          path: '**/node_modules'
          key: ${{ runner.os }}-modules-${{ hashFiles('**/yarn.lock') }}
- name: Install dependencies
        if: steps.yarn-cache.outputs.cache-hit != 'true'
        run: yarn install
- name: Build
        run: yarn build
- name: Generate 404 files
        run: |
          echo "---" > "./dist/apps/portfolio/404.html"
          echo "permalink: /404.html" >> "./dist/apps/<app-name>/404.html"
          echo "---" >> "./dist/apps/<app-name>/404.html"
          cat "./dist/apps/<app-name>/index.html" >> "./dist/apps/<app-name>/404.html"
- name: Deploy
        uses: JamesIves/github-pages-deploy-action@releases/v3
        with:
          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
          BRANCH: master
          FOLDER: dist/apps/<app-name>

Here are some notes on the YAML file

Use Actions Cache in order to save time when installing dependencies.

- uses: actions/cache@v2
        with:
          path: '**/node_modules'
          key: ${{ runner.os }}-modules-${{ hashFiles('**/yarn.lock') }}

Make sure after building the complete, create a 404.html file that same with index.html . Otherwise, it will not resolve the routing if you manually visit the page directly from an URL.

- name: Generate 404 files
        run: |
          echo "---" > "./dist/apps/portfolio/404.html"
          echo "permalink: /404.html" >> "./dist/apps/<app-name>/404.html"
          echo "---" >> "./dist/apps/<app-name>/404.html"
          cat "./dist/apps/<app-name>/index.html" >> "./dist/apps/<app-name>/404.html"

After the new setup, the CI/CD time reduced significantly from ~7 minutes to less than 1 minute. You can take a look at the example run.

dalenguyen/dalenguyen.github.io

This is the end of my note, hope that you’ll find it useful.