Technical Guidelines

Technical Guidelines for developers

Aliases

module-alias is a handy tool that allows you to create custom module paths and aliases within your project. This can be particularly useful in larger projects or monorepos, where relative paths can become complex and hard to manage.

Alias Configuration

Next, you'll need to add your custom paths and aliases to your package.json file. Add a _moduleAliases object to your package.json file, where the keys are your aliases and the values are the paths they should resolve to:

  "_moduleAliases": {
    "@oslo-core": "./lib"
  },

In this example, @oslo-core will resolve to the project root, @oslo-core will resolve to the lib directory.

Note: The paths are relative to the location of the package.json file.

Usage in TypeScript

In your TypeScript files, you can now use these aliases in your import statements:

import type { IConfiguration } from '@oslo-core/interfaces/IConfiguration';

Registering Aliases at Runtime

module-alias needs to register the aliases at runtime. To do this, add the following line to the main entry point of your application:

import 'module-alias/register';

In our setup, this will typically be in de runner.ts file or in the index.ts, depending on the package.

TypeScript Configuration

For TypeScript to understand these aliases, you'll need to add a paths option to your tsconfig.json file:

{
  "compilerOptions": {
    "baseUrl": ".", // This must be specified if "paths" is.
    "paths": {
      "@oslo-converter-uml-ea/*": ["packages/oslo-converter-uml-ea/lib/*"],
      "@oslo-core/*": ["packages/oslo-core/lib/*"],
      "@oslo-extractor-uml-ea/*": ["packages/oslo-extractor-uml-ea/lib/*"],
      "@oslo-converter-stakeholders/*": [
        "packages/oslo-converter-stakeholders/lib/*"
      ],
      "@oslo-generator-jsonld-context/*": [
        "packages/oslo-generator-jsonld-context/lib/*"
      ],
      "@oslo-generator-rdf-vocabulary/*": [
        "packages/oslo-generator-rdf-vocabulary/lib/*"
      ],
      "@oslo-generator-respec-html/*": [
        "packages/oslo-generator-respec-html/lib/*"
      ]
    }
  }
}

Note: The paths in tsconfig.json should mirror the paths in your package.json file, but with an extra /* at the end of both the keys and values.

Now, both TypeScript and module-alias understand your custom module paths and aliases. If you were to add a package to this monorepo, you'll need to:

1. Add a new alias in the tsconfig.json mentioned before
2. Install the module-alias as a devDependency
3. Add a _moduleAliases object inside your package.json
4. Import the module in the root of your new package
5. Use the alias in your code and you're good to go!