Project commands

Each project in the monorepo has a project.json file specifying commands and build targets which can be invoked on that project. This document our standard commands and how they should be configured and used.

The commands can be run in these ways

yarn [command] [project] # only for some commands.
yarn nx [command] [project] # for most commands.
yarn nx run [project]:[command] # for all commands.
yarn nx run [project]:[command]:[configuration]

Project names can be found at the top of their respective project.json files and usually matches the path to the project, from the apps and libs folders, with slashes "/" replaced with dashes "-". I.e. the project name for apps/application-system/form is application-system-form.

dev-init (apps)

Used to prepare your workstation for developing the application locally. Usually runs other commands as needed, including:

• dev-services to start databases and other services.

• migrate and seed to create database resources.

• get-secrets to fetch dev secrets from AWS.

• codegen/* to update code generated schemas.

Should be run when starting an application for the first time, switching between branches or pulling latest from main.

dev (apps)

Used to start developing an application. Also starts other applications and services, including as needed:

• X-Road proxy.

• GraphQL API.

• BFF service.

• Required backend services.

Usually run after running dev-init.

serve (apps)

Used to start the application. Also triggered if you run yarn start [application].

build (apps)

Used to build the application. Should be configured to support both development and production builds.

lint (apps, libs)

Used to lint the project, usually with eslint.

test (apps, libs)

Used to run tests in the project, usually with jest.

dev-services (apps)

Used to start databases and other services which the application requires to run locally, usually with docker.

migrate (apps)

Runs database migrations needed by the application. Should run after starting the database with dev-services. Usually part of dev-init.

This command conflicts with the NX migrate command. Use yarn nx run [project]:migrate if you need to run migrate manually.

seed (apps)

Seeds the database with data useful for development. Should run after running database migrations with migrate. Usually part of dev-init.

codegen/*

A set of commands which work together to generate type-safe API schemas and API clients based on API definitions.

Usually invoked across all projects as part of yarn codegen. Can be useful to run manually (or as part of dev-init) after making specific schema changes, since running the full codegen script takes a while to run.

Code Generation

codegen/backend-schema (apps)

Generates an API schema for the application. Usually runs our NestJS application code to export OpenAPI or GraphQL schemas.

codegen/backend-client (libs)

Generates a type-safe API client for backend applications to integrate with other APIs. These commands are usually in client libraries (inside libs/clients) to integrate with our own APIs or for third party APIs.

We use openapi-generator to generate clients based on OpenAPI schemas and graphql-codegen to generate clients based on GraphQL schemas.

Note that openapi-generator does not support advanced OpenAPI features like oneOf and anyOf. Consider using openapi-ts instead.

When creating a client for our own APIs, the client project.json should specify the API application in its implicitDependencies. This makes sure that the API's codegen/backend-schema command is invoked before generating the client with codegen/backend-client.

For third-party APIs, when possible, there should be a update-openapi-document command to fetch a new version of the OpenAPI schema.

codegen/frontend-client (apps, libs)

Generates a type-safe API client for frontend applications to integrate with APIs.

Usually our frontend applications only interact with our GraphQL API, and so we use graphql-codegen to generate clients based on GraphQL schemas.

We recommend using the near-operation-file preset with to generate minimal operation types, reusing the base GraphQL types from @island.is/api/schema.

extract-strings (apps, libs)

Extracts translation strings from the code and updates our CMS so they can be translated.

Requires a valid CONTENTFUL_MANAGEMENT_ACCESS_TOKEN environment variable to run.

docker-* (apps)

These are not real NX commands but rather flags to specify what kind of docker image to build for the application in our CI/CD process. These are implemented in scripts/ci/Dockerfile.

There are 3 valid build configurations:

docker-express-yarn

Builds a docker image to run a NodeJS backend application. Expects the NX build command to be configured with generatePackageJson to dynamically install application specific dependencies inside the docker image.

docker-next

Builds a docker image to run a NextJS application with our custom server.

docker-static

Builds a docker image to host a static web application with nginx.

Other project commands

build-custom-server (apps)

Used by NextJS apps to build our custom server.

serve-custom-server (apps)

Used by NextJS apps to start our custom server.

update-openapi-document (libs)

Can be used to fetch an updated version of OpenAPI schemas for third party APIs.

APIs on X-Road usually have an OpenAPI schema which can be downloaded in a standardized way. Make sure that you have the x-road proxy running on your machine.

Generally, we check in third party API schemas into source control for two reasons:

• To limit dependencies on outside services in our day-to-day development and devops.

• To version or lock down our API client libraries.

start-bff (apps)

Used to start a bff service for a specific frontend application.

worker (apps)

Some backend applications have alternative startup modes, i.e. one-off commands and/or worker mode. Usually we define NX commands to run these locally.

Repo commands

Here are a few commands which are part of the repo which don't belong to a specific project.

yarn proxies

This command starts up proxies on your workstation to access services from our AWS development environment. You need to specify which proxy to start.

You need to have access to the AWS development account and configure your credentials for them to work. Depending on your setup, you may need to specify an AWS_PROFILE when starting proxies:

AWS_PROFILE=islandis-dev yarn proxies [proxy-name]

yarn proxies xroad

Used to connect to the X-Road Security Server in our AWS development environment.

You will run this proxy whenever you are working with third party government APIs. It is often included in project dev commands. Note that you only have access to the IS-DEV X-Road environment.

yarn proxies db

Used to connect to the database in our AWS development environment. To connect to it, you need to manually acquire database credentials from infra files and AWS parameter store.

This is useful to review data in our development environment. It is also useful to use data from our development environment when working on a backend service locally, but we generally recommend replicating the data to your local database instead.

yarn proxies es

Used to connect to ElasticSearch in our AWS development environment.

It is especially useful when working on the web project.

yarn proxies redis

Used to connect to the redis database in our AWS development environment.

yarn codegen

Generate API schemas and type-safe API clients across the whole monorepo. Uses codegen/* commands.

Should run this after cloning the repo and installing dependencies. You may also need to run this after switching branches or getting latest.

Code generation

yarn clean

Removes all node modules, caches, builds and generated code from the monorepo. Can be configured to run partial cleanup.

yarn get-secrets

Used to get development secrets from the AWS parameter store. Requires AWS credentials.

More information

yarn create-secret

Used to create secrets in AWS parameter store for all of our production environments.

Developers can read and write development secrets, but can only write staging and production secrets.

More information

yarn format

Used to format all code in the monorepo. Useful to run before creating a pull request.

yarn charts

Used to generate helm value files for all applications.

Should run this after making any infra configuration changes in apps/[your-app]/infra/[your-app].ts files.