Publicación original en ruso
Mantener su código consistente y bien formateado no es una tarea fácil, incluso cuando trabaja solo. Pero cuando trabajas con un equipo o con un proyecto de código abierto, todo comienza a ser aún más difícil. Todos tienen su propio estilo de código, alguien no ejecuta pruebas y nadie escribe documentación. Este artículo lo ayudará a configurar todas estas cosas y aún más: automatice esta rutina para nunca hacerlo manualmente.
Después de leer, obtendrá su propio proyecto preparado para npm con las siguientes características:
- Formato de texto y estilo de código
- Pruebas automatizadas con cobertura de código y umbral
- Estilo de compromiso unificado
- Documentación generada a partir del código y confirmaciones
- Proceso de publicación automatizado
Vamos!
Prerrequisitos
Cree una nueva carpeta, inicialice un nuevo repositorio, proyecte y vaya al siguiente paso.
git init npm init npm i -D typescript ./node_modules/.bin/tsc --init
Comencemos con el formato de código: tipos de sangría, tamaño, etc. La primera herramienta es el archivo .editorconfig . No requiere nada excepto su IDE y ayuda a mantener su autoformato consistente en todo su equipo.
Cree .editorconfig en la raíz del proyecto con el siguiente contenido (no dude en cambiarlo por el estilo que desee)
#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
Esto es realmente increíble, pero a veces no tiene la potencia suficiente para satisfacer sus necesidades. Para asegurarse de que todo esté bien formateado, aparece más bonito . Si olvida formatear el código, Prettier lo hará por usted.
npm i -D prettier
Agregue este comando a la sección de scripts de su archivo package.json
"prettier": "prettier --config .prettierrc.json --write src/**/*.ts"
Y agregue el archivo .prettierrc.json con su configuración a la raíz del proyecto
{ "tabWidth": 4, "useTabs": false, "semi": true, "singleQuote": true, "trailingComma": "es5", "arrowParens": "always" }
Ahora puede escribir un código e intentar ejecutar "npm run prettier". ¡Prettier verificará la carpeta src y formateará automáticamente su código sin ninguna ayuda de su parte!
Estilo de código
Estilo de código: como evitar el uso de == en lugar de === o las variables de sombreado también deben verificarse. Para este propósito, tomaremos tslint . Si prefiere javascript, tome eslint en su lugar.
npm i -D tslint ./node_modules/.bin/tslint --init
El último comando creará el archivo tslint.json para usted. Mantiene su configuración y ya extiende tslint: conjunto de reglas recomendado, pero puede extenderlas o anularlas como desee. No olvide agregar el comando lint a su package.json.
package.json
"lint": "tslint -c tslint.json 'src/**/*.ts' 'tests/**/*.spec.ts'"
Como lo ves configurado para trabajar con src y carpeta de pruebas, entonces todo tu código debe colocarse allí.
Prueba
Ahora es el momento de configurar nuestras pruebas. Instalar karma y otras dependencias relacionadas
npm i -D karma karma-jasmine jasmine karma-typescript karma-chrome-launcher @types/jasmine ./node_modules/.bin/karma init
Y agregue un nuevo bloque de configuración a karma.conf.js recién creado
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, } } }, }
Esto configurará el archivo de cobertura de código y el nivel de umbral. Ambos son importantes El primero lo ayuda a lidiar con su cobertura y el segundo lo mantiene en cierto nivel.
Update package.json
"test": "karma start"
Y trata de ejecutarlo. No olvides escribir algún código dentro de la carpeta src y las pruebas dentro de la carpeta de pruebas. Así es como se verá su informe de cobertura de código:
Por cierto, si planeas usar una integración continua (como Travis, Jenkins, etc.) es mejor cambiar Chrome runner a HeadlessChrome con titiritero . Para obtener más información sobre HeadlessChrome y CI, consulte mi repositorio de demostración en GitHub.
Comprometer estilo
Por lo general, todos los commits de escritura en algún formato "aleatorio". Entonces, para mantener los compromisos lo suficientemente buenos, se inventó el compromiso . Esta herramienta hace algunas preguntas y genera commit para usted. Otro buen punto es que podemos generar un archivo de registro de cambios a partir de confirmaciones escritas con la ayuda de commitizen.
Instale el adaptador commitizen y convencional-changelog
npm i -D commitizen npm i -D cz-conventional-changelog
Actualizar guiones
"commit":"git-cz"
Agregue una nueva sección de configuración dentro de package.json para commitizen.
"config": { "commitizen": { "path": "./node_modules/cz-conventional-changelog" } }
Intente hacer una confirmación o verifique esta imagen para tener una idea de cómo se verá:
Documentación
Si su proyecto es más grande que unas pocas funciones, es una buena idea tener algo de documentación. Y es aún mejor cuando no necesita escribir algo manualmente. Para eso existe typedoc . Toma sus archivos .ts, sus comentarios jsdoc y crea documentación agradable y brillante. Si está utilizando JavaScript, puede probar esdoc en su lugar.
Aquí hay un ejemplo, cómo typedoc describió mi función esNumberStrict:
npm i -D typedoc
package.json
"doc": "typedoc --out docs/src"
Otra buena idea es hacer que su archivo de registro de cambios también se genere automáticamente. Como mencioné antes, commitizen apoya el registro de cambios convencional. Entonces, podemos hacer commits y convertirlos al archivo de registro de cambios.
Instalar convencional-changelog-cli
npm i -D conventional-changelog-cli
Y actualice package.json con el nuevo comando
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
No se preocupe, angular significa solo formato de estilo y nada más. Ahora, su registro de cambios se formará como se muestra a continuación:
Construir
La compilación es bastante simple y solo es cuestión de agregar comandos de compilación y limpieza al paquete.json
"clean":"rmdir dist /S /Q", "build": "tsc --p ./ --sourceMap false",
Si necesita agrupación o minificación, pruebe uglifyjs .
Automatización
Ok, la mayor parte ya está hecha. Creamos un montón de scripts diferentes para mantener nuestro código limpio y correcto. Pero ejecutarlos cada vez manualmente es una tarea bastante aburrida y puede conducir a errores. Entonces, necesitamos automatizarlos. Como sabes, cuando haces un commit, aparecen algunos eventos git: pre-commit, post-commit, etc. Podemos usarlos para ejecutar nuestros propios scripts antes de que el código se confirme o envíe. Pero hay un problema: los ganchos de git no se pueden compartir. Y es por eso que aparece Husky . Este paquete envuelve los eventos git y ejecuta sus scripts desde package.json. Si la secuencia de comandos falla, se cancelará la confirmación y recibirá el mensaje de lo que va mal.
Instalar husky
npm i -D husky
Y describa algunos ganchos dentro de package.json
"precommit":"npm run prettier", "prepush": "call npm run lint && call npm run test"
Ahora, cuando intente hacer una confirmación más bonita, se ejecutará y solucionará todos los problemas de formato. Cuando intente crear un estilo de código push, las pruebas se realizarán automáticamente. Puede extender estos comandos lo que necesite, como enviar notificaciones, verificación adicional, etc.
Publicar
Genial, ya casi hemos terminado. Entonces, digamos que estamos listos para publicar el paquete en npm. Como saben, se debe hacer mucho trabajo antes: pruebas, actualización de documentación, versión y actualización de etiquetas. Fácil de olvidar algo, ¿sí? Por lo tanto, también es una buena idea automatizar este proceso. Para ello, utilizaremos ganchos nativos npm: preversión, versión y postversión. Agregue las siguientes líneas a la sección de scripts de su paquete.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"
Cuando ejecute el comando npm version, el script de preversión ejecutará pruebas, el script de versión construirá su código y generará todos los documentos. Luego se aumentará la versión y luego todo se confirmará y se eliminará. Ahora todo lo que necesita es ejecutar el comando npm Publish y eso es todo. Solo con los comandos y todo lo demás se hará sin ningún esfuerzo de su parte.
Por último, debemos especificar qué carpetas deben incluirse en el proyecto y dónde se puede ubicar el punto de entrada. Actualizar package.json la última vez
"main": "./dist/index.min.js", "types": "./dist/index.d.ts", "files": [ "dist/", "src/", "tests/" ]
¡Eso es todo, tu increíble proyecto está listo!
Enlaces utiles
Gracias por leer Si tiene alguna pregunta, consulte mi repositorio de demostración aquí o solicite comentarios.
Que tengas un buen día!