Figure out how to handle custom generators

[justinbmeyer]

Before we announce how custom generators work, we should review what we've done.

[phillipskevin]

Here are the use cases I've seen for custom generators and the issues that currently exist:

In each of these, "templates" refers the EJS Templates used by the yeoman generators inside generator-donejs.

1 - Plugins can modify templates used by other plugins (#140 - docs)

Example Use Case:

I want to create a component that uses mocha for its tests by running these commands:

donejs add mocha
donejs add component my-component

Proposed Solution:

This works currently. donejs add mocha overwrites this template:

.donejs/templates/component/modlet/component_test.js

2 - Plugins can rename templates used by other plugins (#141)

Example Use Case:

I want to create a component that uses SASS for its styles by running these commands:

donejs add sass
donejs add component my-component

Proposed Solution (1a):

Generators will store a list of the templates they use in the .donejs folder. For example the component generator would write out

.donejs/templates/component/modlet/templates.json

that would contain this list.

Proposed Solution (1b):

Generators will read the list of files in the template directory and copy them all over.

Issues with solution:

• plugins might want to pass data to the template other than what is passed by default.

3 - Two plugins can modify the same template

Example Use Case (3a):

I want to create a component that uses mocha and CommonJS by running the commands

donejs add mocha
donejs add commonjs
donejs add component my-component

Proposed Solution (3a):

Create utilities for plugins to modify existing plugins using transforms (using something like jscodeshift for JS files).

The donejs-commonjs code would then do something like:

var modifyTemplates = require('donejs-template-utils');
var toCommonJS = require('es6-to-commonjs');

// modifyTemplates will 
// 1. find all templates in `.donejs/templates` that match the glob pattern `**/*.js`
// 2. convert the EJS to JS by replacing any `<%= %>` blocks with some sort of GUID
// 3. pass them through the `toCommonJS` transform
// 4. change the GUIDs back to EJS template tags
// 5. write the template back to the `.donejs/templates` folder they came from
modifyTemplates('**/*.js', [ toCommonJS ])
    .then(function() { 
        console.log('changed everything to CommonJS')
    });

Issues with solution (3a):

• these transforms might be prone to break if new plugins do anything complicated in their templates
• transforms for file types other than JS may be more complicated since they don't have ASTs and would probably have to use regex

Example Use Case (3b):

I want to create a component that uses mocha and CommonJS by running the commands

donejs add commonjs-mocha
donejs add component my-component

Proposed Solution (3b):

Create plugins for all of the combinations of technologies.

• donejs-mocha-es6
• donejs-mocha-commonjs
• donejs-qunit-es6
• donejs-qunit-commonjs
• donejs-jasmine-es6
• donejs-jasmine-commonjs
• etc, etc, etc

Issues with solution (3b):

• Number of plugins grows exponentially as people want different options

[frank-dspeed]

maybe this should use codemods now as thats used now via can-migrate proposed changes to other generators already not finished with all existing generators but i think that would clear also that

[phillipskevin]

@frank-dspeed 3a talks about using codemods. jscodeshift is what can-migrate uses for running codemods.