# Configure for development

To configure SWC for a development environment, execute the following steps.

Open a terminal at the root of the project and install the following packages:

pnpm add -D @workleap/swc-configs @swc/core @swc/helpers

yarn add -D @workleap/swc-configs @swc/core @swc/helpers

npm install -D @workleap/swc-configs @swc/core @swc/helpers

First, create a configuration file named swc.dev.js at the root of the project:

web-project
├── src
├──── ...
├── package.json
├── swc.dev.js

Then, open the newly created file and export the SWC configuration by using the defineDevConfig(targets, options) function:

// @ts-check

import { browserslistToSwc, defineDevConfig } from "@workleap/swc-configs";

const targets = browserslistToSwc();

export const swcConfig = defineDevConfig(targets);

In the previous code sample, the defineDevConfig(targets, options) function receives a list of minimal browser versions to support through the targets parameter.

The expected behavior for the supported browsers would be for SWC to automatically load the minimal browser versions from the closest .browserslistrc configuration file. However, there is currently an issue preventing SWC from doing so when the configuration file include a query referencing an external Browserslist configuration:

extends @workleap/browserslist-config

Therefore, @workleap/swc-configs has chosen to delegate the loading of the Browserslist configuration to the consumer by making the targets option required.

To help consumers provide SWC targets from a Browserslist configuration, @workleap/swc-configs offers the browserslistToSwc(options) utility function.

This function can either transform an array of Browserslist queries to SWC targets:

// @ts-check

import { browserslistToSwc, defineDevConfig } from "@workleap/swc-configs";

const targets = browserslistToSwc({ queries: ["extends @workleap/browserslist-config"] });

export const swcConfig = defineDevConfig(targets);

Or load the closest .browserslistrc configuration file and convert the queries into SWC targets:

extends @workleap/browserslist-config

// @ts-check

import { browserslistToSwc, defineDevConfig } from "@workleap/swc-configs";

const targets = browserslistToSwc();

export const swcConfig = defineDevConfig(targets);

The browserslistToSwc(options) utility function accepts any option supported by Browserslist JS API in addition to a queries option:

• queries: string | string[]

The defineDevConfig(targets, options) function can be used as shown in the previous example, however, if you wish to customize the default configuration, the function also accept a few predefined options to help with that 👇

• Type: string

Sets a base directory from which to resolve module names. This option is usually provided when custom paths are provided. Note that SWC requires the baseUrl to be an absolute path.

// @ts-check

import path from "node:path";
import { browserslistToSwc, defineDevConfig } from "@workleap/swc-configs";

const targets = browserslistToSwc();

export const swcConfig = defineDevConfig(targets, {
    baseUrl: path.resolve("src")
});

• Type: boolean
• Default: true

Whether or not to enable Fast Refresh.

// @ts-check

import { browserslistToSwc, defineDevConfig } from "@workleap/swc-configs";

const targets = browserslistToSwc();

export const swcConfig = defineDevConfig(targets, {
    fastRefresh: false
});

• Type: "ecmascript" | "typescript"
• Default: "typescript"

Whether SWC should expect to parse JavaScript or TypeScript code.

// @ts-check

import { browserslistToSwc, defineDevConfig } from "@workleap/swc-configs";

const targets = browserslistToSwc();

export const swcConfig = defineDevConfig(targets, {
    parser: "ecmascript"
});

• Type: Record<string, string[]>

A series of entries which re-map imports to lookup locations relative to the baseUrl if set.

// @ts-check

import path from "node:path";
import { browserslistToSwc, defineDevConfig } from "@workleap/swc-configs";

const targets = browserslistToSwc();

export const swcConfig = defineDevConfig(targets, {
    baseUrl: path.resolve("src"),
    paths: {
        "@/*": ["*"]
    }
});

The predefined options are useful to quickly customize the default development configuration of @workleap/swc-configs, but only covers a subset of an SWC configuration. If you need full control over the configuration, you can provide configuration transformer functions through the transformers option of the defineDevConfig function. Remember, no locked in ❤️✌️.

To view the default development configuration of @workleap/swc-configs, have a look at the dev.ts configuration file on GitHub.

• Type: ((config: SwcConfig, context: SwcConfigTransformerContext) => SwcConfig)[]
• Default: []

transformer(config: SwcConfig, context: SwcConfigTransformerContext) => SwcConfig

// @ts-check

import { browserslistToSwc, defineDevConfig } from "@workleap/swc-configs";

const targets = browserslistToSwc();

/**
 * @type {import("@workleap/swc-configs").SwcConfigTransformer}
 */
function disableReactBuiltins(config) {
    config.jsc.transform.react.useBuiltins = false;

    return config;
}

export const swcConfig = defineDevConfig(targets, {
    transformers: [disableReactBuiltins]
});

Generic transformers can use the context parameter to gather additional information about their execution context, like the environment they are operating in:

// @ts-check

/**
 * @type {import("@workleap/swc-configs").SwcConfigTransformer}
 */
export function transformer(config, context) {
    if (context.environment === "dev") {
        config.jsc.transform.react.useBuiltins = false;
    }

    return config;
};

• environment: "dev" | "build" | "jest"

To integrate with webpack, update your configuration file to include an swc-loader:

// @ts-check

import { swcConfig } from "./swc.dev.js";

export default {
    ...
    module: {
        rules: [
            {
                test: /\.(js|jsx|ts|tsx)/i,
                exclude: /node_modules/,
                use: {
                    loader: "swc-loader",
                    options: swcConfig
                }
            }
        ]
    }
}

To test your new SWC configuration, create a Typescript file with the following code:

export function say(string: value) {
    console.log(value);
}

If you integrated SWC with webpack, make sure to import the previously created file in one of your webpack entry points, then start the webpack development server. The development server should start without outputting any error to the console.

Otherwise, open a terminal at the root of your project and install @swc/cli:

pnpm add -D @swc/cli @swc/core

yarn add -D @swc/cli @swc/core

npm install -D @swc/cli @swc/core

Then, process the file with @swc/cli by executing the following command in the same terminal:

npx swc ./say.ts -o say.js --config-file swc.build.js

The generated say.js file should include the following transpiled code:

export function say(value) {
    console.log(value);
}