SWC no Node.js

O SWC no Node.js é um compilador rápido escrito em Rust para transformar JavaScript e TypeScript. Ele pode substituir etapas de transpile baseadas em Babel, acelerar builds, compilar decorators e gerar código compatível com versões específicas do runtime.

Assim como outras ferramentas de transformação rápida, SWC não substitui automaticamente o typecheck do TypeScript. Ele remove tipos e converte sintaxe, mas a validação estática continua responsabilidade de tsc --noEmit ou outra etapa equivalente. O resultado também precisa ser testado no Node.js realmente usado em produção.

Neste guia, você aprenderá a instalar SWC, criar um arquivo .swcrc, compilar ESM e CommonJS, usar TypeScript, decorators, sourcemaps, minificação, watch mode, API JavaScript, Jest e CI.

Instalação

npm install --save-dev @swc/core @swc/cli

A documentação oficial de Getting Started do SWC lista binários pré-compilados para macOS, Linux, Alpine e Windows. Em containers Alpine, confirme o pacote musl necessário.

Primeira compilação

npx swc src -d dist

O comando percorre a pasta src e escreve o resultado em dist. Sem configuração, o output pode não corresponder ao formato de módulos desejado, então defina .swcrc.

Configuração básica

{
  "$schema": "https://swc.rs/schema.json",
  "jsc": {
    "parser": {
      "syntax": "typescript"
    },
    "target": "es2022"
  },
  "module": {
    "type": "es6"
  },
  "sourceMaps": true
}

Salve como .swcrc. O schema ajuda editores a validar propriedades.

Script no package.json

{
  "scripts": {
    "build": "swc src -d dist --strip-leading-paths",
    "typecheck": "tsc --noEmit"
  }
}

Veja npm Scripts no Node.js para organizar comandos locais e de CI.

TypeScript sem typecheck

SWC transforma este código:

const amount: number = 'erro';

A anotação é removida, mas o tipo incorreto pode não bloquear o build. Mantenha:

npm run typecheck

Em projetos TypeScript, trate SWC como compilador de emissão e tsc como verificador.

ESM no Node.js

No package.json:

{
  "type": "module"
}

No .swcrc:

{
  "module": {
    "type": "es6"
  }
}

Os imports relativos precisam continuar válidos no output. Se o JavaScript emitido usa .js, escreva caminhos compatíveis com o runtime. Consulte TypeScript ESM no Node.js.

CommonJS

{
  "module": {
    "type": "commonjs"
  }
}

Use quando a aplicação ou consumidor exige require. Não produza dois formatos sem testar exports, tipos e carregamento de cada um.

Target

{
  "jsc": {
    "target": "es2022"
  }
}

Escolha o target conforme a versão mínima do Node.js. Um target muito antigo gera transformações desnecessárias; um target muito novo pode produzir sintaxe não suportada.

Parser TypeScript

{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "tsx": false,
      "decorators": false,
      "dynamicImport": true
    }
  }
}

Habilite apenas recursos usados. Para TSX:

"tsx": true

Decorators

Frameworks como NestJS podem exigir decorators e metadata:

{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "decorators": true
    },
    "transform": {
      "legacyDecorator": true,
      "decoratorMetadata": true
    }
  }
}

Decorators legados e decorators padronizados possuem semânticas diferentes. Alinhe SWC, TypeScript e framework antes de migrar.

React e TSX

{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "tsx": true
    },
    "transform": {
      "react": {
        "runtime": "automatic"
      }
    }
  }
}

Mesmo em projetos Node.js, isso pode ser útil para SSR ou ferramentas que processam componentes.

Sourcemaps

{
  "sourceMaps": true,
  "inlineSourcesContent": false
}

Execute:

node --enable-source-maps dist/server.js

Proteja sourcemaps quando eles contêm código-fonte sensível.

Minificação

{
  "minify": true,
  "jsc": {
    "minify": {
      "compress": true,
      "mangle": true
    }
  }
}

Minificação no backend raramente é a primeira otimização. Ela pode piorar stacks, alterar nomes e dificultar profiling. Meça antes de habilitar.

Variáveis de ambiente

Não incorpore segredos no build. Use variáveis carregadas em runtime. Valores definidos durante compilação ficam visíveis no artefato.

API JavaScript

import { transformFile } from '@swc/core';
import { writeFile } from 'node:fs/promises';

const output = await transformFile('src/server.ts', {
  jsc: {
    parser: { syntax: 'typescript' },
    target: 'es2022'
  },
  module: { type: 'es6' },
  sourceMaps: true
});

await writeFile('dist/server.js', output.code);

A API é útil quando o build precisa de lógica própria, geração de vários formatos ou integração com outras ferramentas.

transform e transformFile

transform recebe código em memória; transformFile lê um arquivo. Para compilar árvores completas, a CLI ou uma ferramenta de bundling tende a ser mais simples.

SWC não é bundler completo por padrão

Compilar arquivos preserva imports. Isso é diferente de incluir dependências em um único arquivo. O projeto possui recursos de bundling, mas avalie maturidade e requisitos. Para bundles Node.js, compare com esbuild no Node.js.

Watch mode

npx swc src -d dist --watch

O watcher recompila arquivos, mas não reinicia automaticamente o servidor em todos os fluxos. Combine com node --watch dist/server.js ou outra ferramenta.

Ignorando arquivos

npx swc src -d dist \
  --ignore '**/*.test.ts' \
  --ignore '**/*.spec.ts'

Mantenha testes fora do artefato quando não são necessários em produção.

Configuração por ambiente

Use env ou arquivos separados quando desenvolvimento e produção exigem targets diferentes. Evite uma configuração com condicionais difíceis de reproduzir.

Jest com SWC

npm install --save-dev @swc/jest

export default {
  transform: {
    '^.+\\.(t|j)sx?$': ['@swc/jest']
  }
};

Verifique suporte a ESM, decorators e aliases. Para projetos novos, o Node Test Runner ou Vitest pode exigir menos configuração.

Node Test Runner

Você pode compilar testes antes de executar:

npm run build:test
node --test dist-test/**/*.test.js

Ou usar um loader compatível, desde que a versão esteja fixada. Veja Node Test Runner.

Bibliotecas

Para publicar uma biblioteca:

• compile JavaScript com SWC;
• gere declarations com tsc --emitDeclarationOnly;
• defina exports;
• marque peer dependencies;
• teste o tarball;
• verifique ESM e CommonJS.

Veja Publicar Pacote no npm.

Declarations

tsc --emitDeclarationOnly --declaration --outDir dist

SWC não substitui a geração de declarações em todos os fluxos. Separe emissão de tipos da transformação rápida.

Monorepos

Em npm Workspaces, cada pacote pode ter .swcrc próprio ou compartilhar uma base. Mantenha targets e formato alinhados. Consulte npm Workspaces no Node.js.

Docker

FROM node:22 AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run typecheck && npm run build

FROM node:22-slim
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY package*.json ./
RUN npm ci --omit=dev
CMD ["node", "--enable-source-maps", "dist/server.js"]

Em Alpine, confirme a variante binária correta do SWC durante o estágio de build.

CI

- run: npm ci
- run: npm run lint
- run: npm run typecheck
- run: npm test
- run: npm run build
- run: node dist/smoke-test.js

O artigo CI para Node.js com GitHub Actions mostra cache, matrix e artifacts.

Desempenho

Compare em seu projeto:

time npm run build:tsc
time npm run build:swc

Meça cold build, rebuild, consumo de memória e tempo total do CI. Uma etapa rápida isolada pode não reduzir o pipeline se typecheck e testes dominam.

Migração de Babel

1. Liste plugins Babel usados.
2. Confirme equivalentes SWC.
3. Crie fixtures de sintaxe.
4. Compare output.
5. Teste sourcemaps.
6. Execute testes de integração.
7. Migre uma etapa por vez.

Plugins Babel muito específicos podem não ter equivalente direto.

Migração de tsc

Se tsc hoje verifica e emite:

1. mantenha tsc --noEmit;
2. configure SWC para emitir;
3. gere declarations separadamente;
4. compare estrutura de dist;
5. execute o artefato;
6. teste publicação.

Segurança

• Fixe versões.
• Revise binários e plugins.
• Não incorpore segredos.
• Proteja sourcemaps.
• Use lockfile.
• Execute build em CI isolada.
• Teste em ambiente limpo.

Erros comuns

• Sem typecheck: erros estáticos passam.
• Formato de módulo errado: runtime falha.
• Decorators incompatíveis: metadata muda.
• Target incorreto: sintaxe não é suportada.
• Declarations ausentes: consumidores TypeScript quebram.
• Minificação sem medir: diagnóstico piora.
• Binário incompatível: container não inicia build.
• Testar só fontes: output não é validado.

Configuração recomendada

{
  "$schema": "https://swc.rs/schema.json",
  "jsc": {
    "parser": {
      "syntax": "typescript"
    },
    "target": "es2022",
    "keepClassNames": true
  },
  "module": {
    "type": "es6"
  },
  "sourceMaps": true,
  "minify": false
}

Conclusão

O SWC no Node.js acelera a transformação de TypeScript e JavaScript, principalmente em projetos com builds frequentes. Configuração de parser, target, módulos e sourcemaps permite adaptar o output ao runtime real.

Mantenha typecheck, declarations e testes separados. Quando decorators, binários e formato de módulos são validados, SWC oferece velocidade sem sacrificar a segurança do processo de build.