Ekosystém JS je obrovský a nikdy nebudeme schopni podporovat všechny nástroje JavaScriptu. Chceme však ostatním open source vývojářům usnadnit vytváření těchto doplňků a ostatním v komunitě DoneJS usnadnit jejich používání. Zde přichází na scénu generátor generátoru DoneJS. Lze jej použít k vytváření modulů, které přidávají funkce do existující aplikace DoneJS.
Pokud jste použili donejs add nw nebo donejs add cordova k vytvoření desktopové nebo mobilní verze vaší aplikace jste již použili generátor DoneJS. Generátory jsou moduly npm, které poskytují generátor Yeoman, který přidává funkcionalitu vaší aplikaci.
V tomto článku si vytvoříte vlastní verzi donejs-jshint, generátoru DoneJS, který přidává JSHint, nástroj pro kvalitu kódu JavaScript a soubor .editorconfig, který pomáhá textovým editorům a IDE definovat a udržovat konzistentní styl kódování. Aktualizuje také npm test skript pro spuštění JSHint s našimi testy.
- Vytvořte projekt na GitHubu
- Inicializujte úložiště jako nový generátor DoneJS
- Nastavte nepřetržitou integraci s Travis CI
- Přidejte soubory šablon .jshintrc a .editorconfig
- Implementujte funkci generátoru
- Otestujte funkčnost ručně
- Zapište testy jednotek pro generátor
- Publikujte plugin na npm
- Ukažte to světu
Kód najdete v úložišti donejs-jshint. Video návod k tomuto článku je k dispozici zde:
Generátor můžeme spustit pomocí:
$ donejs add jshint
V současné době se pouze zeptá, zda chceme použít mezery nebo tabulátory a přepsat package.json pro přidání skriptů npm pro JSHint:
Poznámka: Od donejs-jshint již existuje, použijeme donejs-<username>-jshint s <username> je vaším uživatelským jménem GitHub pro zbytek tohoto článku. Jakmile je publikován, může být použit jako donejs add <username>-jshint .
Nastavení
Vytvoření projektu na GitHubu
K hostování kódu pro projekt použijeme GitHub, což ostatním usnadní přispívat a automaticky spouštět testy v nepřetržité integraci, kterou umožníme později.
Pokud ještě nemáte účet, přejděte na GitHub, zaregistrujte se a postupujte podle nápovědy, jak jej nastavit pro příkazový řádek git . Po dokončení vytvořte nové úložiště z řídicího panelu.
Volání úložiště donejs-<username>-jshint a jeho inicializace prázdný (bez jakýchkoliv výchozích souborů) vypadá takto:
Po vytvoření úložiště jej naklonujte do nové složky:
$ git clone [email protected]:<username>/donejs-<username>-jshint.git
$ cd donejs-<username>-jshint
Inicializace projektu
Pro inicializaci nového generátoru budete potřebovat DoneJS verze 0.9.0+ nainstalovanou globálně. Chcete-li zkontrolovat verzi DoneJS, spusťte
$ donejs --version
Chcete-li nainstalovat DoneJS nebo získat nejnovější verzi, spusťte:
$ npm install donejs -g
V donejs-<username>-jshint nyní můžeme inicializovat nový generátor, velmi podobný nové aplikaci DoneJS, takto:
$ donejs add generator
Generátor položí několik otázek, které by měly být zodpovězeny následovně:
- Pro název projektu stačí potvrdit výchozí hodnotu stisknutím klávesy Enter
- Pro uživatelské jméno nebo organizaci GitHubu zadejte uživatelské jméno GitHubu, kde bylo úložiště vytvořeno
- Na všechna ostatní pole lze také odpovědět výchozím nastavením nebo informacemi, které chcete použít
Jakmile je vše hotovo, poslední výzva vypadá takto:
Nyní generátor inicializuje výchozí rozložení a nainstaluje všechny jeho závislosti.
Nastavení Travis CI
Po dokončení instalace se ujistěte, že je vše správně nastaveno spuštěním:
$ npm test
Tím se spustí některé základní testy generátoru a výsledek se zobrazí na konzole.
Tento příkaz lze také použít k automatickému spouštění testů na serveru pro nepřetržitou integraci. Existuje mnoho serverů CI s otevřeným zdrojovým kódem, z nichž nejoblíbenější je Jenkins, a mnoho hostovaných řešení, jako je Travis CI.
Travis CI budeme používat jako naše hostované řešení, protože je zdarma pro projekty s otevřeným zdrojovým kódem. Funguje s vaším účtem GitHub, který použije k registraci. Po přihlášení přejděte na Accounts (v rozevíracím seznamu pod vaším jménem) povolte donejs-<username>-jshint úložiště:
Možná budete muset kliknout na "Synchronizovat účet" tlačítko pro zobrazení úložiště. Nyní, pokaždé, když zatlačíme na GitHub, testy se spustí automaticky. Můžeme tak učinit pomocí našeho počátečního potvrzení:
$ git add . --all
$ git commit -am "Initial commit"
$ git push origin master
Pokud nyní přejdete na https://travis-ci.org/<your-username>/donejs-<username>-jshint/builds uvidíte, jak běží sestavení a nakonec zezelená (což aktualizuje odznak, který byl přidán do readme.md soubor).
Přidání konfiguračních souborů
Nyní můžeme přidat soubory, které by měl náš generátor vytvořit. Všechny šablony souborů budou vloženy do default/templates/ složka.
.jshintrc
Nejprve přidejte default/templates/.jshintrc soubor, který obsahuje volby pro JSHint:
{
"node": true,
"esnext": true,
"bitwise": true,
"camelcase": true,
"curly": true,
"eqeqeq": true,
"immed": true,
"indent": 2,
"latedef": "nofunc",
"newcap": false,
"noarg": true,
"regexp": true,
"undef": true,
"unused": true,
"strict": false,
"trailing": true,
"smarttabs": true,
"white": false
}
.editorconfig
Dále přidejte default/templates/.editorconfig soubor takto:
; Unix-style newlines
[*]
end_of_line = LF
indent_style = <%= indent_style %>
trim_trailing_whitespace = true
Všechny soubory podporují zástupné symboly EJS. Zde <%= indent_style %> bude použit pro uživatelskou volbu použití mezer nebo tabulátorů. Nakonec odstraňte defaults/templates/file.js protože ji nebudeme používat.
Implementace generátoru
Generátory DoneJS jsou z velké části jednoduše generátory Yeoman, takže vše zdokumentované pro psaní vlastního generátoru Yeoman platí i zde. Uživatelský výběr tabulátorů a mezer naleznete také v kapitole o interakci s uživatelem.
Přidání funkcí generátoru
Náš generátor se musí zeptat, zda chceme použít mezery nebo tabulátory, a poté zkopírovat .jshintrc a .editorconfig soubory do jejich konečného umístění. Chceme také přidat npm run jshint skript na package.json a ujistěte se, že JSHint běží během npm test . Kompletní generátor na default/index.js vypadá takto:
var generator = require('yeoman-generator');
var _ = require('lodash');
module.exports = generator.Base.extend({
initializing: function () {
// Read the original package.json
this.pkg = this.fs.readJSON(
this.destinationPath('package.json'), {}
);
// Maintain a list of all files we want to copy over
this.files = [
'.editorconfig',
'.jshintrc'
];
},
prompting: function () {
var done = this.async();
// Create a prompt setting the `indent_style` property
// to `tab` or `space`
this.prompt([{
type: 'list',
name: 'indent_style',
message: 'What indentation style do you want to use?',
default: 'tab',
choices: [
{
name: 'Tabs',
value: 'tab'
},
{
name: 'Spaces',
value: 'space'
}
]
}], function (answers) {
this.props = answers;
done();
}.bind(this));
},
writing: function () {
var pkg = this.pkg;
// Update `package.json` with the `jshint` command
// and update the `test` script
pkg.scripts = _.extend(pkg.scripts, {
test: 'npm run jshint && ' +
_.get(pkg, 'scripts.test',
'echo "No tests specified"'),
jshint: 'jshint ' +
_.get(pkg, 'system.directories.lib',
'src') +
'/. --config'
});
// Write to `package.json` and format accordingly
// This will prompt you to overwrite
var indent = this.props.index === 'tab' ? '\t' : ' ';
this.fs.writeJSON('package.json', pkg, null, indent);
// Install jshint as a development dependency
this.npmInstall([ 'jshint' ], { saveDev: true});
// Got through every file and copy it
this.files.forEach(function(file) {
this.fs.copyTpl(
this.templatePath(file),
this.destinationPath(file),
this.props
);
}.bind(this));
}
});
A je to. Nyní máme plně funkční generátor a můžeme jej vyzkoušet v aplikaci DoneJS.
Ruční testování
Při spuštění donejs add <generatorname> DoneJS bude
- Zkontrolujte, zda
donejs-<generatorname>je nainstalován lokálně - Pokud jej nenainstalujete z NPM
- Potom spusťte generátor na
default/index.js
Pokud chceme náš generátor otestovat, aniž bychom jej nejprve publikovali na npm, můžeme jej místo toho propojit. Ve složce generátoru spusťte:
$ npm link
Poté přejděte do adresáře vaší testovací aplikace DoneJS:
$ cd ../place-my-order
$ npm link donejs-<username>-jshint
Nyní můžeme běžet
$ donejs add <username>-jshint
Psaní testu jednotek
Yeoman také přichází s některými nástroji pro testování generátorů. Test, který jsme původně spustili s npm test zajišťuje, že default/templates/file.js se píše. Protože jsme tento soubor smazali, aktualizujte test na test/index.js pro ověření, že zapsal požadované soubory s obsahem, který očekáváme:
var path = require('path');
var helpers = require('yeoman-test');
var assert = require('yeoman-assert');
describe('donejs--jshint', function() {
before(function(done) {
// Run the generator in a temprorary directory
helpers.run(path.join(__dirname, '../default'))
.inTmpDir()
// Mock the user input by setting
// `indent_style` to `tab`
.withPrompts({
'indent_style': 'tab'
}).on('end', done);
});
// Verify that `.jshintrc` got written
// and has some content
it('created .jshintrc', function() {
assert.file(['.jshintrc']);
assert.fileContent('.jshintrc',
/"latedef": "nofunc"/);
});
// Verify that `.editorconfig` got written
// with `indent_style` set to our selection
it('.editorconfig with indent_style', function() {
assert.file(['.editorconfig']);
assert.fileContent('.editorconfig',
/indent_style = tab/);
});
// Make sure that `package.json` got updated
// with the `jshint` npm script
it('update package.json', function() {
assert.jsonFileContent('package.json', {
scripts: {
jshint: 'jshint src/. --config'
}
});
});
});
Nyní vidíme, jak všechny testy prošly při spuštění:
$ npm test
Publikování pluginu
Vytvoření požadavku na stažení
I když na generátoru zatím pracujeme sami, žádosti GitHub o stažení jsou skvělým způsobem, jak sledovat náš pokrok a ujistit se, že všechny testy projdou. Ve složce pluginu spusťte:
$ git checkout -b generator-functionality
$ git add . --all
$ git commit -m "Implementing JSHint and editorconfig generator"
$ git push origin generator-functionality
A poté vytvořte nový požadavek na stažení pomocí https://github.com/<username>/donejs-<username>-jshint který nyní zobrazí možnost, jako je tato:
Jakmile vytvoříte požadavek na stažení, uvidíte Some checks haven’t completed yet zpráva, která nakonec zezelená:
Nyní můžete kliknout na tlačítko "Merge pull request". Poté v konzole zaškrtněte master větev a stáhnout nejnovější změny pomocí:
$ git checkout master
$ git pull origin master
Publikování na npm
Aby ostatní mohli používat váš generátor přes donejs add <generatorname> musí to přetáhnout na npm. Vytvořte si nový účet a poté se přihlaste přes
$ npm login
Sémantické verzování je skvělý způsob, jak komunikovat nové funkce a přelomové změny. Vygenerovaný plugin je již dodáván se skripty pro vydání nových verzí podle major.minor.patch schéma. V našem případě publikovat počáteční verzi 0.1.0 můžeme běžet
$ donejs release:minor
Nyní verze 0.1.0 generátoru je k dispozici a každý jej může používat prostřednictvím
donejs add <username>-jshint
Ukažte to
Jakmile svůj generátor zveřejníte, dejte o něm vědět světu. Tweetujte @donejs a zveřejněte jej na fóru DoneJS a na chatu DoneJS. Jsou to také skvělá místa, kde získáte rychlou pomoc s případnými dotazy.