Como rodar TypeScript com Experimental Strip Types e evitar erros no Fastify
Veja como configurar scripts no package.json para rodar seu servidor TypeScript usando Node.js com suporte à flag --experimental-strip-types e evitar problemas com tipos, como o uso de type-only imports
Por que isso é importante
Quando trabalhamos com TypeScript no backend usando Node.js, é essencial entender como os tipos são tratados no tempo de execução. Rodar os arquivos diretamente via Node sem build exige cuidados com a importação de tipos. Usar a flag correta evita erros inesperados e acelera o desenvolvimento.
Configurando o script de desenvolvimento no package.json
O primeiro passo é criar um script para iniciar o servidor. No seu package.json, adicione um script chamado dev com a flag --experimental-strip-types para que o Node.js saiba lidar com arquivos TypeScript diretamente.
package.json, crie um script dev: "dev": "node --watch --loader tsx --experimental-specifier-resolution=node --experimental-strip-types src/server.ts".npm run dev e observe a saída no terminal.Entendendo o erro com tipos do Fastify + Zod
Ao executar o servidor, é comum se deparar com um erro relacionado a módulos não encontrados. Isso acontece porque certos tipos como o ZodTypeProvider não são tratados como tipos puros após o strip de tipos do Node.
⚠️Atenção
O erro ocorre porque, mesmo após "remover os tipos", o Node ainda tenta interpretar um type como módulo padrão. Sendo assim, devemos destacar explicitamente que se trata de um import apenas de tipo.
A correção consiste em ajustar a importação para o formato import type { ZodTypeProvider } from 'fastify-type-provider-zod'. Assim, o Node ignora esse trecho no runtime por ser apenas tipo, resolvendo o problema.
Eliminando os ExperimentalWarnings
Ao usar recursos experimentais como strip types, o Node emite avisos constantes. Para evitar que eles poluam seu terminal durante o desenvolvimento, podemos desativá-los diretamente no script.
ℹ️Dica
Adicione --no-warnings=ExperimentalWarning logo após o comando para ocultar essas mensagens.
Adicionando o modo watch automático
A flag --watch reinicia automaticamente o servidor sempre que um arquivo é salvo. Isso acelera bastante o feedback durante o desenvolvimento.
ℹ️Atenção
Certifique-se de estar utilizando Node.js 20+ com suporte à flag --experimental-watch nativamente.
Script de produção (sem watch)
Para rodar sua aplicação em produção, remova a flag --watch e os warning flags. Crie um script start no package.json que rode o mesmo comando, porém sem --watch.
✅Importante
Ter scripts separados para desenvolvimento e produção evita conflitos e mantém o ambiente de runtime mais limpo.
Ferramentas utilizadas
Fastify + Zod
Framework web e validador de tipos para rotas
Node.js 20+
Versão mínima recomendada para usar flag --experimental-strip-types