Guia de Criação de Lib TypeScript

Este guia explica como estruturar uma biblioteca em TypeScript, configurar aliases, compilar para uma pasta lib e publicar no npm.

1. Estrutura básica do projeto

lib-root/
├── src/
│   ├── utils/
│   │   └── hasValue.ts
│   └── index.ts
├── lib/  <-- saída do TypeScript (outDir)
├── package.json
├── tsconfig.json
└── README.md

• src/ → código fonte da biblioteca
• lib/ → arquivos compilados pelo TypeScript (outDir)
• index.ts → ponto central de exportação da lib

2. tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "declaration": true,
    "declarationMap": true,
    "outDir": "lib",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "baseUrl": "src",
    "paths": {
      "@utils/*": ["utils/*"]
    }
  },
  "include": ["src"]
}

Explicação:

• outDir: "lib" → define a pasta de saída da build
• baseUrl: "src" → define o ponto de referência para aliases
• paths: { "@utils/*": ["utils/*"] } → permite importar assim:

import { hasValue } from '@utils/hasValue';

• declaration: true → gera arquivos .d.ts de tipagem
• declarationMap: true → gera mapas para depuração de tipagem

3. index.ts (export centralizado)

// src/index.ts
export * from '@utils/hasValue';

Isso permite importar a lib inteira apenas com:

import { hasValue } from 'lib-root';

4. package.json

{
  "name": "lib-root",
  "version": "1.0.0",
  "description": "Biblioteca utilitária em TypeScript",
  "main": "lib/index.js",
  "types": "lib/index.d.ts",
  "scripts": {
    "build": "tsc",
    "dev": "ts-node src/index.ts"
  },
  "keywords": [],
  "author": "Seu Nome",
  "license": "ISC",
  "devDependencies": {
    "@types/node": "^24.3.0",
    "ts-node": "^10.9.2",
    "typescript": "^5.9.2"
  }
}

Importante:

• main → arquivo principal compilado (lib/index.js)
• types → arquivo de tipagem (lib/index.d.ts)
• scripts.build → comando para gerar a build (npm run build)

5. Compilando a lib

npm run build

• Compila todos os arquivos de src/ para lib/
• Gera .js e .d.ts

6. Publicando no npm público

1. Login no npm

npm login

Informe:

• Username
• Password
• Email

2. Publicar

npm publish --access public

• --access public garante que a lib fique pública
• Após publicar, qualquer projeto pode instalar via:

npm install lib-root

7. Usando a lib em outro projeto

import { hasValue } from 'lib-root';

console.log(hasValue("teste")); // true

8. Resumo

• src/ → código fonte
• lib/ → saída compilada (outDir)
• tsconfig.json → configurações de build + aliases (@utils)
• package.json → main e types corretos para npm
• npm run build → compila a lib
• npm login → autenticação
• npm publish --access public → publica a lib