Greenwood init command and templates

[thescientist13]

Overview

It would be great if there was an easy way for users to initialize a Greenwood project and have all the scaffolding provided including

• package.json with @greenwood/cli pre-installed
• greenwood.config.js
• src/ directory with an initial page

├── greenwood.config.js
├── .gitignore
├── package.json
└── src/
             └─ pages/
                        └─ index.md

Additionally, GitHub repos could be used as templates to easily provide a ready made starting point that could easily be shared with users and not dependent on being coded / configured / bundled directly into the init command itself.

Proposal

Create a new init package in the monorepo that can be invoked via npm / npx and that supports scaffolding as well as pulling from a predefined (or custom) template

Some examples

// just spits out the bare minimum scaffolding
$ npx @greenwood/init

// use a predefined Greenwood template, which would just be its own GitHub repo
$ npx @greenwood/init --template=blog

// use a forked or custom Greenwood template, which can be a _users_ own GitHub / GitLab / etc repo
$ npx @greenwood/init --template=github:<username>/<repo-name>

Additionally in future iterations, init could also ask for / do more things like

• running npm init
• asking for name / location of the package
• installing more dependencies / plugins

Action Items

Let's plan the work out across a few PRs, iterating incrementally following this rough sequence

1. Create new init package that can generate a bare bones Greenwood repo - It would be nice to have a greenwood init/template scaffold command #777
   • greenwood.config.js
   • src/pages/index.md directory
   • package.json
   • README.md (maybe with some nots for how to get started, link to docs
2. Introduce a --template=xxx flag that can consume from an existing repo and scaffold it out file for file
   • Let's create at least one repo for this in our org, e.g. greenwood-template-blog and expose blog as the first template type option - As a developer, it would be nice if I could quickly scaffold from a curated list of templates via cli #841
3. Allow someone to prefix the value for --template with github and provide their own repo location
   • Let's have one of us fork the greenwood-template-blog and use that for testing, eg.

     $ npx @greenwood/init --template=github:thescientist13/greenwood-template-blog

---

From there we can evaluate and prioritize other features and enhancements

• Support installs from GitLab or Bitbucket repos
• Prompt for additional configurations with the default init command
• Ability to install plugins via init

[hutchgrant]

should we include the ability to create the project directory or are we under the assumption they've already created a project directory ?

[thescientist13]

I think it's safe to assume that we are operating in the cwd. I think that's what most init tools do I assume, but might be good to do a quick survey to see if there is an established convention.

Perhaps later on we could add a --dir flag so someone could do both at once? e.g.

$ npx @greenwood/init --dir ./my-new-app

Not sure but I think it's safe to assume . for now, at least to start.

cc: @aholtzman

[hutchgrant]

Rather than copy a default package.json over as we did with create-evergreen-app should we instead execute npm init and npm i @greenwood/cli ?

[hutchgrant]

Another issue with this is we need to modify the package.json to have the greenwood build and develop scripts etc.

[thescientist13]

Hmm, running npm init for them is something I hadn't considered but is an interesting idea. I think most tools assume you will run it. Typically they just scaffold things out then let you take over. Maybe another opportunity to cross reference the DX workflows of other similar tools.

Though it does raise a good question about what the init contents of package.json should look like. I know to publish you need things like name and version (and I assume some others) though for the sake of development I don't think anything prevents us from just spitting out something like this

{
  "scripts": {
    "start": "greenwood develop",
    "build": "greenwood build",
    "serve": "greenwood server"
  },
  "devDependencies": {
    "@greenwood/cli": "~0.y.z"
   }
}

Though I'm sure we could easily stub out the name from the current folder name or eventually ask the user as a feature?

I think if at minimum we can spit something out that allows them to npm i && npm start then we're in a good place so that we can get into a package and add some tests, then we can enrich that experience / package.json and basically just put in as much work as time allows. 🙌

[hutchgrant]

What kind of folder structure should we be expecting for a template. Take the getting-started repo for example, perhaps not all those files are needing to be scaffolded. Maybe only the required files should be placed in template directory ? Or we just assume everything in a template repo should be scaffolded. How is that any different than just doing a git clone ? I suppose if you already have some pages, you could run @greenwood/init --template blog and it would copy over just the needed files rather than replace.

[thescientist13]

Maybe only the required files should be placed in template directory ? Or we just assume everything in a template repo should be scaffolded. How is that any different than just doing a git clone ?

Yeah, I was thinking at least the initial thing to try was just grab from the repo directly and then just only filter through the files we would actually care about, like

• greenwood.config.js
• package.json
• src/

You could also look into using degit.

Perhaps if someone does want all the files in the repos, that could be done by adding another flag?

$ npx @greenwood/cli --template=blog --all

---

As a note, I wouldn't get too hung up on the implementation details, just because it is as easy as a git clone to the grab the contents, doesn't diminish the value of also then preparing the right files and getting things installed and setup all in one command. Once you the nail the outcome, you can always refactor under the hood over time.

[hutchgrant]

I also think it would be a good idea to curate some "suggested" templates that one can select from a list in the CLI

[thescientist13]

Yup, I think that's covered in the section action item and that we would start initially with a blog template. I can make the repo if we need; greenwood-template-blog.

[thescientist13]

Just calling out we should probably really flesh out the current blog starter, as it doesn't really "work" per se. For example, none of the links work. Now that we have refreshed the website, perhaps we can also refresh the styles of the starter as well
https://github.com/ProjectEvergreen/greenwood-template-blog

[thescientist13]

I think now that we have a good implementation around this we can move more specifically to what kind of template / project options we want to commit to and build out for the init command, so have created a dedicated discussion for this - #1335