Setup Sequence

Steps to create the setup sequence:

geenee lets you create a "placeholder" builder for whatever type of app you are templating. You can think of it as the equivalent of what create-react-app is for a React application. So if you want the world to use a certain type of app, you can make a placeholder version quickly with geenee.

Steps

We assume that you are following the steps to create a template, and have already defined in a console session a $SAMPLE path to an application from which to template. Also, that you have defined $TEMPLATE as the path to your template.

1. Come up with a list of programs that you executed and packages you installed to create $SAMPLE. (If you didn't create $SAMPLE, and you don't know whether they called any special tools, you'll just have to figure out what packages to install.)

   Your goal here is to run any program or install any package that would be a common denominator for the type of code base you are templating. So any packages that are specific to business logic that it only relevant to $SAMPLE should be ignored here.

2. Specify the setup sequence as described in the next section.

3. Generate code to confirm that your setup code is generating a code base.

   CODE=$SAMPLES/code
   ns generate $CODE -t $TEMPLATE

   You should see this:

   ? ns generate $CODE  -t $TEMPLATE
     ✔ Create Starter Directory
     ✔ Execute Pre-Commands
     ✔ Install General Packages...
     ✔ Install Dev Packages...
     ✔ Add Meta-Data

   You can inspect the code in $CODE and make sure everything looks about right.

   Then use diff to find the differences between $CODE and $SAMPLE. Here is a good call to try: DIFFS_FILE=~/ns/diffs diff -qr --exclude=node_modules \ --exclude=.git \ $SAMPLE/ $CODE/ | sort \ | sed "s|$SAMPLE|\$SAMPLE|g" \ | sed "s|$CODE|\$CODE|g" \ | sed "s|: |\/|g" \ | sed "s|Only in \$SAMPLE/|not being generated: |g" \ | sed "s|Only in \$CODE/|new added: |g" \ > $DIFFS_FILE

   You also should check the json file to see whether any dependencies in $SAMPLE that are not added for specific business logic are also showing up in $CODE:

   DIFFS_FOR_FILE=~/ns/diffs-for-file
   FILE=package.json
   diff $SAMPLE/$FILE $CODE/$FILE

   If there are, you should add them to the config in mainInstallation or devInstallation as described below, then again run generate.

   You can always update things and try again, so don't worry too much.

Then return to the steps to create a template.

Following is more information if you need it.

Setup Specification

You can place in your config file a setupSequence object, which executes a sequence of commands. See the config file for the sample template as a model.

There are four keys under setupSequence:

1. interactive

2. preCommands

3. mainInstallation

4. devInstallation

Each is discussed in its own section.

The first time you do this, just try getting one step to work and running generate, then work your way to a complete list.

interactive

You may start the process of generating code by running any number of interactive programs. These can even be bash scripts included in your template file. You specify a list, and they get executed in the same order. For each, provide:

• file the name of the command or bash script that you want to execute. (Note: npx is usually the best option for a released package. That lets you get the latest version and removes the need for a template user to have something installed globally. So, rather than running oclif, you would run npx and make oclif the first argument)

• arguments the list of arguments passed into the command. These are strings.

  There is currently one general variable that you can use in arguments: $codeDir. The value of $codeDir is whatever the name of the code base that gets passed by the user to ns generate.

• options an optional list of the options for child_process.

An example of an interactive entry would be this:

setupSequence:
    ...
    interactive:
       - file: npx
         arguments:
           - oclif
           - multi
           - $codeDir

This list consists of a single command--running oclif using npx. The name that gets passed to oclif as an argument should be replaced by the name of your $SAMPLE code.

All of the interactive list will be executed in order. The user will have the opportunity to insert anything needed as prompted.

Note It is actually better to insert any command that is not interactive [that executes without user interactions] under precommands as specified below. It is better to have multiple templates that leave as little as possible up to the user running ns generate. The only reason for interactive is that some programs do not allow you to specify options programmatically, so you have to run them interactively.

preCommands

This is a list of uninteractive files or programs that get executed automatically in the order that you place them. * A title will show up when your template user watches the progress from the command prompt. * The same 3 keys shown in interactive above: file, arguments and perhaps options.

The purpose of preCommands is to run tools like createReactApp. Note that you could create a bash script, stored in your template directory, to execute. So you have the ability to run whatever sequence you like.

mainInstallation

This is an array of packages that get installed by npm. See the sample config file.

devInstallation

An array of packages that get installed by npm for dev.

Again, see the sample config file.

Leaving Versions Dynamic

A big goal of geenee is to let you have the latest of everything in your stack, so we encourage this approach rather than providing a hardcoded package.json file. On the debit side, you need to be sure to update any code if conflicts arise with the latest versions of packages used.

If need be, you can of course hardcode the version of a package listed in mainInstallation or devInstallation, e.g. '@apollo/[email protected]' in the config file for the sample template.