G1Joshi/Agent-Skills

SWC

SWC (Speedy Web Compiler) é uma plataforma extensível baseada em Rust. É o compilador interno do Next.js e Deno.

Quando Usar

• Transpilação de Alto Desempenho JavaScript/TypeScript: Substituir Babel por um compilador Rust até 20x mais rápido.
• Pipelines Next.js e Bundlers Modernos: Transpilar React JSX, TSX, funcionalidades modernas do ECMAScript e assets Webpack/Turbopack.
• Manipulação Programática de AST e Geração de Código: Construir ferramentas de build customizadas rápidas usando a API Node.js @swc/core.
• Minificação de Assets de Produção: Minificar bundles JS e CSS em velocidades extremas usando o minificador @swc/core.

Início Rápido

1. .swcrc Mínimo

{
  "$schema": "https://json.schemastore.org/swcrc",
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "tsx": true,
      "decorators": true
    },
    "transform": {
      "react": {
        "runtime": "automatic"
      }
    },
    "target": "es2022"
  },
  "minify": false
}

2. Compilar via CLI

npx @swc/cli src -d dist

Conceitos Principais

Configuração de Produção SWC (.swcrc)

Configurando TypeScript moderno, runtime React 19 JSX e transpilação de módulos:

{
  "$schema": "https://json.schemastore.org/swcrc",
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "tsx": true,
      "decorators": true,
      "dynamicImport": true
    },
    "transform": {
      "react": {
        "runtime": "automatic",
        "refresh": true
      }
    },
    "target": "es2022",
    "loose": false,
    "externalHelpers": true,
    "keepClassNames": true,
    "minify": {
      "compress": {
        "unused": true,
        "drop_console": true
      },
      "mangle": true
    }
  },
  "module": {
    "type": "es6"
  },
  "minify": true,
  "sourceMaps": true
}

Compilação Programática com a API @swc/core

Transpilando arquivos fonte de forma assíncrona em scripts Node.js:

import swc from "@swc/core";
import fs from "node:fs/promises";

async function compileTypeScript(filePath) {
  const code = await fs.readFile(filePath, "utf-8");

  const output = await swc.transform(code, {
    filename: filePath,
    sourceMaps: true,
    jsc: {
      parser: { syntax: "typescript", tsx: true },
      target: "es2022",
    },
    module: { type: "commonjs" },
  });

  console.log("Código Transpilado:\n", output.code);
  if (output.map) {
    console.log("Source Map Gerado");
  }
}

compileTypeScript("./src/index.ts");

Transpilação CLI de Alta Velocidade

Compilando árvores de diretórios diretamente com a linha de comando SWC:

# Transpilar src/ para dist/ com source maps
npx swc src -d dist --copy-files --source-maps

# Transpilar e empacotar com swcpack
npx swc src/index.ts -o dist/bundle.js --minify

Padrões Comuns

Acelerando Testes Jest com @swc/jest

Problema: A transpilação TypeScript com ts-jest torna as suítes de teste muito lentas. Solução: Substitua ts-jest por @swc/jest.

// jest.config.js
module.exports = {
  transform: {
    "^.+\\.(t|j)sx?$": [
      "@swc/jest",
      {
        jsc: {
          transform: {
            react: { runtime: "automatic" },
          },
        },
      },
    ],
  },
};

Pipeline de Empacotamento e Minificação SWC

Problema: Necessidade de minificação rápida para scripts de build de produção. Solução: Ative as opções minify dentro do .swcrc.

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

Melhores Práticas (2026)

• Faça instale @swc/helpers e ative externalHelpers: true para evitar duplicação de stubs de runtime do transpilador.
• Faça combine SWC com tsc --noEmit em pipelines CI/CD, pois SWC transpila código sem realizar verificação de tipos.
• Faça configure target: "es2022" ou mais novo para aproveitar capacidades nativas de navegadores modernos.
• Faça use @swc/jest ou @swc/register para acelerar drasticamente a execução de testes unitários.
• Não faça dependa de plugins Babel a menos que estritamente necessário; verifique se existem plugins SWC nativos (plugins Wasm).
• Não faça envie diretórios de cache de build do .swc para repositórios Git.
• Não faça execute a minificação SWC sem gerar source maps para solução de problemas em produção.

Solução de Problemas

Erro / Sintoma	Causa	Solução
failed to handle: error parsing typescript	Sintaxe TypeScript (ex.: JSX ou decorators) usada sem ativar flags no .swcrc	Certifique-se de que "syntax": "typescript", "tsx": true e "decorators": true estejam em jsc.parser.
Metadados de decorators não emitidos (Reflect.getMetadata retorna undefined)	transform.legacyDecorator e transform.decoratorMetadata não configurados	Defina "legacyDecorator": true e "decoratorMetadata": true dentro de jsc.transform.
Cannot find module '@swc/core-darwin-arm64'	Falha na instalação do binário nativo durante npm/yarn install	Execute npm install --force @swc/core para acionar a busca do binário nativo para a arquitetura alvo.

Referências

• Documentação SWC