Skip to main content

Migrating an application into the monorepo

This guide will walk you through migrating your code from your existing repository into this one, while keeping your git history intact.

Migrating a Create React App? There is another doc for SPA Build Plugin which should be your first choice of migrating a SPA into the monorepo. This will make the way into the DNB micro applications, easier.

Feature freeze​

We recommend a feature freeze while moving your code, meaning that you have no other commits in your repository while you're moving. Unless you're a git high wizard, you'll find it complicates matters a lot if you have to keep two repos in sync while at the same time redefining the directory structure of your code. Do yourself a favor and keep it simple.

Git history​

In order to keep your earlier git history, there are some useful tips to keep in mind. Before you start:

It is our recommendation that you do not try to migrate parts of your repo at a time or over a period of time, this might cause problems in your git history. Also, the migration is a good time to do pair programming so there's more eyes on the "dugnad" at the same time.

  • Merge all open PR's

  • Make sure you don't have anything locally you haven't merged to Master-branch

  • Feature-freeze your repository

  • Always use git add . & git commit, as it preserves the history of the file being moved. git commit -am does not.

Steps to follow​

  1. Create a migration branch on the original repo (eg. core/migrate-{application})

  2. In the monorepo create a receiving branch (eg. {name-space}/migration)

  3. Under the apps-folder, create a temp folder for your application. It should look like this:

apps/
  {name-space}/
    .temp/
  1. In the original repo create the same folder structure around the applications and files you want to move. In pm-netbank, we surrounded the whole original repo file structure with
apps/
  {name-space}/
    .temp/
      all apps and configs
  1. In the monorepo, add you original repo as a remote

git remote add {original-repo-name} {path-to-original}

  1. In the monorepo, pull the originals migration branch

git pull {original-repo} core/migrate-{application} --allow-unrelated-histories

Your original repo should now be present under apps/{name-space}/.temp/.

Remember to commit after this before you start migration into Gatsby applications.

Move from .temp to Gatsby

Important: always use git add . & git commit, as it preserves the history of the file being moved.git commit -am does not.

We want to move appA from;

apps/
  team1/
    .temp/
      appA

to a framework app using Gatsby in

apps/
  team1/
    appA/
  1. Create an empty Gatsby app using the NX cli tool

yarn nx g app team1/appA

This will create a (mostly) empty Gatsby application that is tied to the framework. Read more about what that means in the 'Create app or library' page.

  1. You can start moving files and folders from .temp/appA into the team1/appA, where they fit. The Gatsby structure mostly resembles most common React-apps but differs in the way the application is handled (see step 3.)

team1/appA:

apps/
  team1/
    appA/
      src/
        components/
        hooks/
        pages/
          appA/
            index.js <-- the entrypoint for the App
        providers/
        routes/
        services/
      static/

      ...config-files and others
  1. In common React apps index.js uses ReactDOM to render the app to a DOM element. In Gatsby we flatten out all the components into pages. Every component inside /pages will get a "code-splited" chunk, that the users gets later as an individual HTML page.

Its a good practice to move one set of files or a file at a time and run git add . & git commit with a message "Move appA components" before continuing

  1. When you have moved all hooks, providers, components etc. to the Gatsby App, and run yarn install (don't forget to add your dependencies to package.json) you can serve the Gatsby app with yarn nx serve team1/appA

  2. You can run your test with yarn nx test team1/appA, NX uses Jest behind the scenes and all .spec and .test files should run

Side note: NX also creates an application to run e2e test with Cypress (much like puppeteer). Run it with yarn nx e2e team1/appA-e2e
e2e test are written with Cypress and are placed in the integration folder under /team1/appA-e2e/src/integration/app.spec.js

Routing​

Read more about routing in Routing And Pages.

If your tests are dependant on .env​

in .jest/setEnvVars.js

process.env.MY_CUSTOM_TEST_ENV_VAR = 'foo'

and make sure the jest.config points to the right file

module.exports = {
  setupFiles: ["<rootDir>/{team-space}/{application-name}/.jest/setEnvVars.js"]
};

Running tests with NX​

Tests run smoother with the nx test command (compared to running jest directly), and will make use of the cached results from previous runs. e.g. yarn nx test pm-netbank/i18n.