#Configuring Modern.js

There are two configurations in the Modern.js, a compile configuration and a server runtime configuration.

The compile configuration can be configured in two places:

• modern.config.(ts|js|mjs) file in the root path
• package.json file

Server runtime configuration can be configured in the modern.server-runtime.config.(ts|js|mjs) file in the root path.

#Configure in the configuration file

Modern.js configuration files are defined in the root path of the project, and supports .js, .ts and .mjs formats:

• modern.config.js
• modern.config.ts
• modern.config.mjs

#modern.config.js

You can use JavaScript syntax in the modern.config.js file and it is more flexible than in the package.json file.

For example, you can define configuration options for function types in modern.config.js:

export default {
  source: {
    alias: opts => {
      opts['@common'] = './src/common';
    },
  },
};

You can also dynamically set it with process.env.NODE _ENV:

export default {
  server: {
    ssr: process.env.NODE_ENV === 'development',
  },
};

#modern.config.ts (recommended)

We recommend using configuration files in .ts format, which provides friendly TypeScript type hints to help you avoid configuration errors.

Import the defineConfig tool function from @modern-js/app-tools, which will help you with configuration type derivation and type completion:

import { defineConfig } from '@modern-js/app-tools';

export default defineConfig({
  source: {
    alias: {
      '@common': './src/common',
    },
  },
});

#Export Configuration Function

Modern.js supports exporting a function in the configuration file, and you can dynamically compute the configuration in the function and return it to Modern.js.

import { defineConfig } from '@modern-js/app-tools';

export default defineConfig(({ env, command }) => ({
  source: {
    alias: {
      '@foo': env === 'development' ? './src/foo.dev.ts' : './src/foo.prod.ts',
    },
  },
}));

This function takes the following parameters:

• env: same as the value of process.env.NODE_ENV.
  • When running modern dev or modern start, the value of env is development.
  • When running modern build or modern serve, the value of env is production.
  • When running modern test, the value of env is test.
• command: corresponds to the currently running command, such as dev, start, build, serve.

#Export Async Function

Modern.js also supports exporting an asynchronous function in the configuration file, you can perform some asynchronous operations in the function:

import { defineConfig } from '@modern-js/app-tools';

export default defineConfig(async ({ env, command }) => {
  const result = await someAsyncFunction();

  return {
    html: {
      title: result,
    },
  };
});

#Specify the Configuration File

You can specify the name of the configuration file using the --config option.

For example, if you need to use the modern.prod.config.js file when running build, you can add the following scripts to package.json:

{
  "scripts": {
    "dev": "modern dev",
    "build": "modern build --config modern.prod.config.js"
  }
}

You can also abbreviate the --config option to -c:

$ modern build -c modern.prod.config.js

#Configure in package.json (not recommended)

In addition to configuration files, configuration options can also be set the modernConfig field in the package.json, such as:

{
  "modernConfig": {
    "source": {
      "alias": {
        "@common": "./src/common"
      }
    }
  }
}

Due to the limitation of the JSON file format, only simple types such as numbers, strings, boolean values, arrays, etc. can be defined in package.json. When we need to set the value of the function type, it is recommended to set it in the Modern.js configuration file.

#Note

• It is not recommended to use both package.json and modern.config.t[j]s for configuration. If both are used and a configuration conflict occurs, Modern.js will prompt error on the command line.
• @modern-js/runtime exports the defineConfig API of the same name, please pay attention to the distinction.

#Debug configuration locally

To facilitate local debugging configuration locally, Modern.js supports creating modern.config.local.(ts|js|mjs) files in the root directory of the project to override modern.config.(ts|js|mjs) configurations.

#Example

For example, the port number is configured as 3000 in modern.config.ts:

import { defineConfig } from '@modern-js/app-tools';

export default defineConfig({
  server: {
    port: 3000,
  },
});

If you need to change the port number to 3001 to debugging locally, but you don't want to change the modern.config.ts file of the current project, you can create a modern.config.local.ts file and add the following configuration:

import { defineConfig } from '@modern-js/app-tools';

export default defineConfig({
  server: {
    port: 3001,
  },
});

The configuration in the modern.config.local.ts file will be deep merged with the configuration in modern.config.ts and override the configurations in modern.config.ts, so server.port will be is overridden by 3001.

#Note

When using modern.config.local.ts, please note the following:

• The modern.config.local.ts file is only loaded when running modern dev or modern start commands, and will not be loaded when running modern build.
• The modern.config.local.ts file overrides not only over modern.config.ts, but also the modernConfig field in package.json.
• As modern.config.local.ts is only used for local debugging, it is not recommended to commit it to the repository, please ensure that the project's .gitignore file contains modern.config.local.ts.

modern.config.local.ts
modern.config.local.js
modern.config.local.mjs