Post original em russo
Manter seu código consistente e bem formatado não é uma tarefa fácil, mesmo quando você trabalha sozinho. Mas quando você trabalha com uma equipe ou com um projeto de código aberto, tudo começa a ficar ainda mais difícil. Todo mundo tem um estilo de código próprio, alguém não executa testes e ninguém escreve documentação. Este artigo ajudará você a configurar todas essas coisas e ainda mais - automatize essa rotina para nunca fazer isso manualmente.
Após a leitura, você obterá seu próprio projeto pronto para npm com os seguintes recursos:
- Formatação de texto e estilo de código
- Testes automatizados com cobertura e limite de código
- Estilo de consolidação unificada
- Documentação gerada a partir do código e confirma
- Processo de publicação automatizado
Vamos lá!
Pré-requisitos
Crie uma nova pasta, inicialize o novo repositório, projete e vá para a próxima etapa.
git init npm init npm i -D typescript ./node_modules/.bin/tsc --init
Vamos começar com a formatação do código - tipos de indentação, tamanho e assim por diante. A primeira ferramenta é o arquivo .editorconfig . Ele não requer nada, exceto o IDE, e ajuda a manter o autoformato consistente em toda a sua equipe.
Crie .editorconfig na raiz do projeto com o próximo conteúdo (fique à vontade para alterá-lo para o estilo desejado)
#root = true [*] indent_style = space end_of_line = lf charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true max_line_length = 100 indent_size = 4 [*.md] trim_trailing_whitespace = false
Isso é realmente incrível, mas às vezes não há energia suficiente para atender às suas necessidades. Para garantir que tudo esteja bem formatado, apareça. Se você esquecer de formatar o código, mais bonito fará isso por você.
npm i -D prettier
Inclua este comando na seção scripts do arquivo package.json
"prettier": "prettier --config .prettierrc.json --write src/**/*.ts"
E adicione o arquivo .prettierrc.json com suas configurações à raiz do projeto
{ "tabWidth": 4, "useTabs": false, "semi": true, "singleQuote": true, "trailingComma": "es5", "arrowParens": "always" }
Agora você pode escrever um código e tentar executar "npm run pretty". O Prettier irá verificar a pasta src e formatar automaticamente o seu código sem qualquer ajuda do seu lado!
Estilo do código
Estilo de código - como evitar usar == em vez de === ou sombrear variáveis também precisa ser verificado. Para esse fim, usaremos tslint . Se você preferir javascript - use o eslint .
npm i -D tslint ./node_modules/.bin/tslint --init
O último comando criará o arquivo tslint.json para você. Ele mantém suas configurações e já estende o tslint: conjunto de regras recomendado, mas você pode estendê-las ou substituí-las conforme desejar. Não esqueça de adicionar o comando lint ao seu package.json.
package.json
"lint": "tslint -c tslint.json 'src/**/*.ts' 'tests/**/*.spec.ts'"
Como você vê a configuração para trabalhar com a pasta src e tests, todo o seu código deve ser colocado lá.
Teste
Agora é hora de configurar nossos testes. Instale karma e outras dependências relacionadas
npm i -D karma karma-jasmine jasmine karma-typescript karma-chrome-launcher @types/jasmine ./node_modules/.bin/karma init
E adicione um novo bloco de configuração ao karma.conf.js recém-criado
karma.conf.js karmaTypescriptConfig : { include: ["./src/**/*.ts", "./tests/**/*.spec.ts"], tsconfig: "./tsconfig.json", reports: { "html": "coverage", "lcovonly": { directory: './coverage', filename: '../lcov.dat' } }, coverageOptions: { threshold: { global: { statements: 60, branches: 60, functions: 60, lines: 60 }, file: { statements: 60, branches: 60, functions: 60, lines: 60, } } }, }
Isso configurará o arquivo de cobertura de código e o nível do limite. Ambos são importantes. O primeiro ajuda você a lidar com sua cobertura e o segundo mantém sua cobertura em um determinado nível.
Atualizar package.json
"test": "karma start"
E tente executá-lo. Não esqueça de escrever algum código dentro da pasta src e testar dentro da pasta testes. É assim que o seu relatório de cobertura de código será:
Aliás, se você planeja usar a integração contínua (como Travis, Jenkins ou assim por diante), é melhor alterar o runner do Chrome para HeadlessChrome com marionetista . Para mais informações sobre o HeadlessChrome e o CI - consulte meu repositório de demonstração no GitHub.
Estilo de confirmação
Geralmente, todas as gravações são confirmadas em algum formato "aleatório". Portanto, para manter os commits bons o suficiente, o commitizen foi inventado. Essa ferramenta solicita algumas perguntas e gera commit para você. Outro ponto positivo é que podemos gerar um arquivo de log de alterações a partir de confirmações escritas com a ajuda do commitizen.
Instale o commitizen e o adaptador de registro de alterações convencional
npm i -D commitizen npm i -D cz-conventional-changelog
Scripts de atualização
"commit":"git-cz"
Adicione nova seção de configuração dentro do package.json para o commitizen.
"config": { "commitizen": { "path": "./node_modules/cz-conventional-changelog" } }
Tente fazer um commit ou verifique esta imagem para ter uma idéia de como será:
Documentação
Se o seu projeto for maior que algumas funções, é uma boa ideia ter alguma documentação. E é ainda melhor quando você não precisa escrever algo manualmente. Para esse efeito, existe o typedoc . Leva seus arquivos .ts, seus comentários jsdoc e cria uma documentação agradável e brilhante. Se você estiver usando JavaScript - tente o esdoc .
Aqui está um exemplo, como typedoc descreveu minha função éNumberStrict:
npm i -D typedoc
package.json
"doc": "typedoc --out docs/src"
Outra boa idéia é tornar seu arquivo de log de alterações gerado automaticamente. Como mencionei antes, o commitizen suporta o changelog convencional. Portanto, podemos aceitar confirmações e convertê-las no arquivo de log de alterações.
Instale o changelog-cli convencional
npm i -D conventional-changelog-cli
E atualize o package.json com o novo comando
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
Não se preocupe, angular significa apenas formatação de estilo e nada mais. Agora, seu changelog será formado como abaixo:
Construir
A compilação é bastante simples e é apenas uma questão de adicionar comandos de compilação e limpeza ao package.json
"clean":"rmdir dist /S /Q", "build": "tsc --p ./ --sourceMap false",
Se você precisar de empacotamento ou minificação - tente uglifyjs .
Automação
Ok, a maior parte já foi feita. Criamos vários scripts diferentes para manter nosso código limpo e correto. Mas executá-los sempre manualmente é uma tarefa bastante chata e pode levar a erros. Então, precisamos automatizá-los. Como você sabe, quando você faz um commit, alguns eventos git aparecem - pré-commit, pós-commit e assim por diante. Podemos usá-los para executar nossos próprios scripts antes que o código seja confirmado ou enviado por push. Mas há um problema - os ganchos do Git não são compartilháveis. E é por isso que husky aparece. Este pacote agrupa os eventos git e executa seus scripts a partir do package.json. Se o script falhar, a confirmação será cancelada e você receberá a mensagem que está dando errado.
Instalar rouca
npm i -D husky
E descreva alguns ganchos dentro do package.json
"precommit":"npm run prettier", "prepush": "call npm run lint && call npm run test"
Agora, quando você tenta fazer um commit mais bonito, ele será executado e corrigirá todos os problemas de formatação. Quando você tenta criar um estilo de código push, os testes são feitos automaticamente. Você pode estender esses comandos para o que precisar, como enviar notificações, verificação extra etc.
Publicar
Ótimo, estamos quase terminando. Então, digamos que estamos prontos para publicar o pacote no npm. Como você sabe, muito trabalho deve ser feito antes - testes, atualização da documentação, versão e atualização de tags. Fácil esquecer algo, certo? Portanto, é uma boa ideia automatizar esse processo também. Para isso, usaremos hooks nativos do npm - preversão, versão e pós-versão. Adicione as próximas linhas à seção scripts do seu package.json
"preversion": "npm run test", "version": "call npm run clean && call npm run build && call npm run doc && call npm run changelog && git add . && git commit -m 'changelogupdate' --no-verify", "postversion": "git add . && git push && git push --tags"
Quando você executa o comando npm version, o script de versão anterior executa testes, o script de versão cria seu código e gera todos os documentos. A versão será aumentada e tudo será confirmado e enviado. Agora tudo que você precisa é executar o comando npm publish e pronto. Apenas para comandos e tudo o mais será feito sem nenhum esforço do seu lado.
Por fim, precisamos especificar quais pastas devem ser incluídas no projeto e onde o ponto de entrada pode ser localizado. Atualizar package.json da última vez
"main": "./dist/index.min.js", "types": "./dist/index.d.ts", "files": [ "dist/", "src/", "tests/" ]
Isso é tudo, seu projeto incrível está pronto para começar!
Links úteis
Obrigado pela leitura. Se você tiver alguma dúvida, verifique meu repositório de demonstração aqui ou pergunte nos comentários.
Tenham um bom dia!