formidablelabs / builder-init Goto Github PK

Goals / Task

• Make <archetype>[dev/|]/package.json available as template data.

Original Proposal

So that you can do this in init/package.json:

  "dependencies": {
    "builder": "~2.2.0",
    "builder-react-component": "^<%= archetypePackage.version %>"
  },
  "devDependencies": {
    "builder-react-component-dev": "^<%= archetypePackage.version %>",
    "chai": "^3.2.0",
    "mocha": "^2.3.3",
    "react": "^0.14.0",
    "react-addons-test-utils": "^0.14.0",
    "react-dom": "^0.14.0",
    "sinon": "^1.17.2",
    "sinon-chai": "^2.8.0"
  }

This probably obviates the need to implement FormidableLabs/builder-support#7

/cc @chaseadamsio

Since we npm pack PACKAGE from a temp directory, when using NPME, you need a user level (aka, ~/.npmrc) and not a "current working directory" one which won't take effect.

• Basic usage section
• File layout: init.js, init/
• Example: Init from local file.
• Example: Init from github.
• Example: Init from npm.
• Note: Destination directories cannot already exist.

It would be great if there is a command that could auto generate a class and a spec file for the class.

For e.g. builder run generate MyClass would generate MyClass and also generate a spec file for the class.

Two strawmen options:

1. Put it in init.js as an "excludes: FUNCTION" thing that gets the finished data object from all user prompts and derived promptes and can then be applied to the output, resolved file list.
2. Have something in the ​_template files themselves_​ that enables / hooks to "don't write this file at all"

module.exports = {
  prompts: {
    redux: {
      message: "Create a Redux-aware component?",
      default: false
    },
  },

  excludes: (data, fileList, cb) {
    fileList = fileList.filter(function (name) {
      // Exclude redux files if no redux.
      if (!data.redux && /src\/[actions|reducersmiddleware]\//.test(name) {
        return false;
      }

      return true;
    });

    cb(null, fileList);
  }
};

Scenario: We have a templates in <archetype>/init/ that have some data field that is not gathered / created in <archetype>/init.js

Task:

• Add some way of inferring all needed props in templates and erroring if not present
• Complexity: But, need to handle props that can be empty... (shouldn't be an issue?)

• Use logging of certain features like builder.
• Logging levels (or punt to builder ticket)
• Maybe a builder-logger project?

I don't know if this is already possible and I missed it.

I'd like to have multiple different init folders like

+ init-react
+ init-reactwithrouter
+ init-somethinelse

and I'd like to allow the user when running builder-init to choose which one to use.

Is this possible already or would this need to be implemented?

I'm trying to use the "File Name Parsing" feature of builder-init:

This works (https://github.com/plotly/dash-components-archetype/tree/template-file-name-prompt):

• I have in init.js a {{packageName}} prompt
• I have an init/{{packagename}}.txt file

Result:

~/dev/plotly/test$ builder-init "`pwd`/../dash-components-archetype"
dash-components-archetype-0.1.3.tgz
[builder-init] Preparing templates for: dash-components-archetype
? Please name your component suite. foo-prompted
? Enter a description Dash UI component suite
? GitHub organization or user name
? License organization (e.g., you or your company)
? Destination directory to write foo-prompted

[builder-init] Wrote files:
 - foo-prompted/.babelrc
 - foo-prompted/.builderrc
 - foo-prompted/LICENSE.txt
 - foo-prompted/README.md
 - foo-prompted/package.json
 - foo-prompted/.eslintrc
 - foo-prompted/.gitignore
 - foo-prompted/.npmignore
 - foo-prompted/foo-prompted.txt
 - foo-prompted/src/index.js
 - foo-prompted/src/components/ExampleComponent.react.js

[builder-init] New dash-components-archetype project is ready at: foo-prompted

This does not work (https://github.com/plotly/dash-components-archetype/tree/template-file-name-derived):

• I have in init.js a {{capitalCamelCasePackageName}} derived field
• I have an init/{{capitalCamelCasePackageName}}.txt file

Result:

EDITED: I copy-pasted the wrong error here before.

~/dev/plotly/test$ builder-init "`pwd`/../dash-components-archetype"
dash-components-archetype-0.1.3.tgz
[builder-init] Preparing templates for: dash-components-archetype
? Destination directory to write yeah-man
Error: Unknown token: 'capitalCamelCasePackageName' for path: /var/folders/dr/4nn6l7t17cvdjcmx6tdtvgrr0000gp/T/builder-init116530-32509-elt0x8/extracted/init/{{capitalCamelCasePackageName}}.txt

Note: When using the derived field, the first prompt is "? Destination directory to write", not "? Please name your component suite."

Repro:

git clone [email protected]:plotly/dash-components-archetype.git
cd dash-components-archetype
git checkout template-file-name-derived
npm install

cd ..
npm install -g builder-init
builder-init "`pwd`/../dash-components-archetype"
# now enter a valid package name like "foo-component-suite"

Probably as external plugin. Provide an easy way of "choose a license enum + files".

• Options: MIT, BSD, GPL, Apache, etc.

• Support a way to do "proxy through the git branch I'm installing from" for actual prod and dev deps. (Dev is potentially harder because of git and /dev/ directory).
  • This is complicated by a wontfix npm feature request for support for this: npm/npm#2974

Scenario: We potentially have non-git-included extra files in <archetype>/init/ that we want to ignore and not process (like .DS_Store, etc.)

Task:

• Apply a filter to only process non-.gitignore-ed files from archetype (E.g., /Users/rye/scm/fmd/builder-react-component/init/.DS_Store)

Research and add a scripts functionality for things like having a project after initialization do:

$ npm install
$ node_modules/.bin/builder run check-ci

Task:

• Research scripts use cases and implement.
• Consider defaults tasks like npm install if nothing supplied.
  • Allow user to override and have "nothing" run

• Do actual CLI with arguments and flags (share with builder?)
• From NPM (at a version?)
• From filesystem
• From GitHub / generic git (at a version?)
• Maybe do GH ORG/PROJECT shortcut if possible (?) (Like use npm internals)
• Hook up to Travis CI to actually init an archetype and run the new project's CI commands.

Optional:

• builder-init help #5
• init.js:scripts #12

On my Windows 10 machine with node 5.6.0 & npm 3.6.0...

C:\Code> npm -g install builder-init
C:\Users\Stephen\AppData\Roaming\npm\builder-init -> C:\Users\Stephen\AppData\Roaming\npm\node_modules\builder-init\bin\builder-init.js
C:\Users\Stephen\AppData\Roaming\npm
`-- [email protected]

All seems OK...

C:\Code\my-project> builder-init
Usage:

  builder-init [flags] <archetype>

Flags:
...

But...

C:\Code\my-project> builder-init builder-react-component
Error: spawn npm ENOENT
    at exports._errnoException (util.js:856:11)
    at Process.ChildProcess._handle.onexit (internal/child_process.js:178:32)
    at onErrorNT (internal/child_process.js:344:16)
    at nextTickCallbackWith2Args (node.js:475:9)
    at process._tickCallback (node.js:389:17)

Have I done something wrong?

Kind regards,

Stephen

PS. Builder looks like it could be a serious time saver. Brilliant work!

PNGs in archetype get mangled by templating

Currently, init.js can only require locally available files in the archetype and standard Node libraries. It cannot require normal npm dependencies because an archetype's dependencies aren't installed. (See #32 ). This is actually a good thing because we don't want to have the time of a full npm install before starting the template prompts because in our common case, the prompts don't need nearly any of those dependencies.

Task:

• Create a scheme for having dependencies from npm available to init.js.
  • Strawman: Add a dependencies field to init.js. If present, manually npm install DEP1 DEP2 etc. in the extracted/ directory so init.js can use them.

/cc @coopy

The -- propagation is very naive right now as well as builder detection. In this case, we only propagate to one of the two tasks:

// package.json
    "one": "echo one",
    "two": "echo two",
    "all": "builder run one && builder run two"

Produces this:

$ builder run all -- --hi
[builder:proc:start] Command: builder run one && builder run two -- --hi
[builder:proc:start] Command: echo one
one
[builder:proc:start] Command: echo two --hi
two --hi

Task:

• Propagate the flag to builder ... && builder ... tasks (maybe via environment?)
• Have more sophisticated builder task detection for echo NOT_BUILDER && builder run <task> too

We have a generic templating tool here that's not builder specific, so let's move that to it's own project

• Move all of lib/ to new project.
• Move the bin/builder-init.js logic to a lib/ library and leave a very small shell.
• Take default prompts values as an argument to executor in new project.
• Proposal: Make all tool-provided automatic values prefaced with an _. So, e.g., instead of eslint, npmignore, etc. we'd have _eslint, _npmignore, etc. in new tool
  • Deprecate eslint, npmignore, etc. in builder-init and provide transition aliases and documentation.
• Open Question: Make destination into _destination and just another normal field that if empty blows up?

New list of proposed default fields:

/**
 * Default prompts values added to all prompt calls.
 */
var DEFAULTS = {
  destination: {
    message: "Destination directory to write",
    validate: function (val) { /* existing stuff */ }
  },
  derived: {
    // Existing renamed file name helpers.
    _npmignore: function (data, cb) { cb(null, ".npmignore"); },
    _gitignore: function (data, cb) { cb(null, ".gitignore"); },
    _eslintrc: function (data, cb) { cb(null, ".eslintrc"); },
    _npmrc: function (data, cb) { cb(null, ".npmrc"); }

    // New stuff
    //
    // Location of templates directory to use.
    // Default to `init` for `builder-init`. Could be anything for new project.
    // https://github.com/FormidableLabs/builder-init/issues/36
    _templatesDir: /* snipped */
  }
};

/cc @kenwheeler

In downloading / extracting an archetype, we go through creating a temp directory, a process spawn (npm pack), ungzip, untarring to the temp directory and walking that file path. There's a lot that can go wrong with very terse / hard-to-understand error messages.

Task:

• Review and add error wrappers to make captured errors much more accesible.
• Add information to error about where things went wrong.

Scenarios:

• Archetype doesn't have init.js
• Archetype doesn't have init/

We npm pack in a temp directory which breaks how npm would act in a directory - this exact solution was applied to FormidableLabs/publish-diff#8 which also uses npm pack + temp dirs.

I guess I can answer my own question by putting this into practice, but I've just found this package and it's a bit late.

But what I would expect to have happen is when I push a new release of a builder-init archetype, I should also want to update other repos that are built on that archetype to reflect the new changes.

• do I just rerun builder-init?
• if so, do existing files get overwritten?
• do new files get created if they are added in a later update from the version of the archetype initially used to initialize the project?

Thanks a bunch in advance! Love the work you guys do at Formidable.

• Basic init.js file + structure (METADATA)
• Validation
  • Missing props (Captured separately in #8)
  • Validators: "", must match regex for file path, etc.
• Dynamic:
  (1) default, and/or
  (2) actual value from some other value
• Tests

Notes:

• npm uses https://github.com/npm/init-package-json which uses https://github.com/npm/promzard
  • Promzard can't reprompt on invalid input.
• https://github.com/flatiron/prompt has a lot of community backing
• https://github.com/sboudrias/Inquirer.js looks full featured, but has a lot of dependencies.

Include:

• npm run builder:check
• npm run builder:build + git commit results (or as part of the preversion git committing (?))

/cc @coopy

Left behind because we reuse tests from denim at intermediate version.