Skip to content

Latest commit

 

History

History
301 lines (214 loc) · 8.16 KB

integrations.md

File metadata and controls

301 lines (214 loc) · 8.16 KB
Raw

Integrations

Use configured path aliases in a variety of IDEs, tooling and frameworks

Jump to:

IDEs

VS Code

Follow the instructions in the Configure paths document and VS Code should pick up your paths.

See the VS Code documentation for more information.

WebStorm

The following configuration file can be used to tell WebStorm about your Webpack setup.

Add this file to your project root, and choose it in Preferences > Languages and Frameworks > JavaScript > Webpack:

// webpack.config.js
import hq from 'alias-hq'

module.exports = {
  resolve: {
    alias: hq.get('webpack')
  }
}

Tooling

Webpack

If bundling using Webpack, you can add the aliases using the resolve.alias configuration option:

// build.js
import hq from 'alias-hq'

module.exports = {
  ...
  resolve: {
    alias: hq.get('webpack'),
  },
}

Rollup

Basic setup

If bundling using Rollup you will need to use the @rollup/plugin-alias plugin.

Install, then add the aliases using the plugins.alias configuration option:

// rollup.config.js
import hq from 'alias-hq'
import alias from '@rollup/plugin-alias';

module.exports = {
  ...
  plugins: [
    alias({
      entries: hq.get('rollup')
    })
  ]
}

You can request paths in object (the default) or array format:

hq.get('rollup', { format: 'array' })

Bundling with TypeScript

If your bundle is to be consumed by other projects, you will need to set up additional plugins. This is because the TypeScript compiler (rather strangely) doesn't transform aliased paths in its generated type files.

The plugin ts-transform-paths will rewrite aliases in the compilation step, using the rollup-plugin-typescript2 plugin, which is arguably the most reliable TypeScript bundling plugin for Rollup.

Full instructions here:

Vite

Vite uses Rollup under the hood, and passes some of its configuration options to it.

Add a vite.config.js file to your project's route with the following code:

import { defineConfig } from 'vite'
import hq from 'alias-hq'

export default defineConfig({
  resolve: {
    alias: hq.get('rollup')
  }
})

Jest

If using Jest, you can configure the moduleNameMapper option:

// jest.config.js
import hq from 'alias-hq'

module.exports = {
  ...
  moduleNameMapper: hq.get('jest'),
}

You can request the individual paths in string (the default) or array (Jest v25+) format:

hq.get('jest', { format: 'array' })

Babel

If using Babel, you can use the Babel plugin Module Resolver.

Open your babel.config.js file and configure as so:

const hq = require('alias-hq')

module.exports = {
  ...
  plugins: [
    ['module-resolver', {
      root: ['./'], // must match tsconfig.json srcUrl
      alias: hq.get('babel'),
    }],
  ],
}

For more info, check the plugin's docs.

Frameworks

Vue

If using Vue CLI, you can add the aliases using the configureWebpack or chainWebpack option.

Decide which one to use, then update as appropriate:

// vue.config.js
import hq from 'alias-hq'

module.exports = {
  configureWebpack: (config) => {
    ...
    Object.assign(config.resolve.alias, hq.get('webpack'))
  },
}

React

React takes a little more work than the other options, depending on how you are using it.

Create React App

Unfortunately, Create React App out-of-the-box does not allow path aliases, and will physically rewrite your config if you attempt to use them.

To work around this, at least two options are:

  • eject the configuration and manually add Alias HQ to config/webpack.config.js (see above)
  • use something like React App Rewired to enable the webpack setup to be manually tweaked (see below)

React App Rewired

To prevent Create React App from rewriting your tsconfig:

  1. Rename your tsconfig.json file as tsconfig.base.json
  2. Create a new tsconfig.json file and save the following:
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {}
}

To set up React App Rewired:

  1. Follow the installation instructions to install in your project
  2. Set up the config-overrides.js file as follows:
const hq = require('alias-hq')

module.exports = function override(config, env) {
  Object.assign(config.resolve.alias, hq.get('webpack'))
  return config;
}

This short React guide is not meant to be exhaustive; for issues, use your common sense, search Google, and see the appropriate package's issues.

React Native

React Native's bundler Metro uses Babel to transpile, so you will need to install the Babel plugin Module Resolver first, which can then be configured by Alias HQ:

npm install babel-plugin-module-resolver --save-dev 
yarn add metro-react-native-babel-preset -D

Next modify your default babel.config.js configuration, adding the plugin and configuring with Alias HQ:

const hq = require('alias-hq')

module.exports = {
  ...
  plugins: [
    ['module-resolver', {
      root: ['./'], // must match tsconfig.json srcUrl
      alias: hq.get('babel'),
      extensions: [
        '.ios.js',
        '.android.js',
        '.native.js',
        '.js',
        '.jsx',
        '.json',
        '.tsx',
        '.ts',
      ],
    }],
  ],
}

For more information, check:

Other

Node

Although Node doesn't support path aliases natively, the module-alias package modifies Node's require() to add support for path aliases. There are some caveats but Alias HQ supports it via a plugin.

Either, add the following line in your application's main file, before requiring any @aliased paths:

require('alias-hq').get('module-alias')

Or, register paths automatically using Node's require flag and Alias's Node-specific init export:

{
  "scripts": {
    "start": "node -r alias-hq/init src/index.js",
    "watch": "nodemon --exec node -r alias-hq/init src/index.ts",
  },
}

JSON-only

For libraries or setups that require JSON, you can use the CLI:

  • Run the CLI by typing alias-hq in the terminal
  • Choose "Dump plugin output (JSON)"
  • Choose the required format
  • Copy / paste the JSON where you need it