0.20.0 release branch (ESM migration)

[thescientist13]

Related Issue

resolves #532 (continuation of #707)

Summary of Changes

1. Migrated await entirely from ESM, including all specs and (most) dependencies
2. make all exports explicit by making them named exports #551
3. have init lock step initial version to current Greenwood version #816
4. switch to c8 for ESM code coverage #818
5. favor using latest when documenting npx commands #821
6. add a section on scripts and imports to the docs section #822
7. release v0.20.0 blog post #825

Alpha Release Test Plan

I think given the impact of this change, it would be wise for us to cut from a release branch instead of merging right into main so that

• we can test this in the wild first and ensure all our docs / examples / refactoring is correct
• we're not stuck with broken code in master while under pressure to fix things

The plan would be to test against the following projects / workflows as alpha releases are iterated upon:

1. greenwood-getting-started - upgrade to v0.20.0-alpha.0 and node 14 greenwood-getting-started#53
2. projectevergreen.github.io - upgrade to v0.20.0-alpha.0 and node 14 projectevergreen.github.io#73
3. thegreehouse.io - upgrade to v0.20.0-alpha.0 and node 14 thegreenhouseio/www.thegreenhouse.io#253
4. contributary.community - upgrade to v0.20.0-alpha.0 and node 14 ContributaryCommunity/www.contributary.community#103
5. analogstudios.net - upgrade to v0.20.0-alpha.0 and node 14 AnalogStudiosRI/www.analogstudios.net#53
6. greenwood-starter-presentation - upgrade to v0.20.0-alpha.0 and node 14 thescientist13/greenwood-starter-presentation#53
7. npx - 0.20.0 release branch (ESM migration) #815 (comment)
8. npx @greenwood/init - 0.20.0 release branch (ESM migration) #815 (comment)
9. Stackblitz - 0.20.0 release branch (ESM migration) #815 (comment)

This PR should NOT be squashed merged though when merging into master.

TODOs

1. Update init package.json to start from 0.20.0 - have init lock step initial version to current Greenwood version #816
   • and / or fix keep init command in sync with latest stable Greenwood CLI version when scaffolding package.json #781 / init command is not self upgrading to latest (sem) version of Greenwood #809
2. Restore Babel plugin extend feature + test case - restore support for extending babel configuration #817
3. Update GitHub Actions and project to min version Node v14 - Node 14x minimum version #721
4. Restore Test Coverage (NYC) - switch to c8 for ESM code coverage #818
   • Nyc on ESM Node.js 13 (no babel) istanbuljs/nyc#1287 (https://github.com/istanbuljs/esm-loader-hook or c8)
5. alpha.1
6. Can we also resolve...? Mostly!
   • add full client API support for Apollo client in plugin-graphql (as ESM) #535 - not right now, see comment
   • make all exports explicit by making them named exports #551 - done as part of Chore/issue 532 esm upgrade #707
   • ensure a clear and consistent convention for when to use file extensions #536 - add a section on scripts and imports to the docs section #822
7. Review and apply this guide if applicable
8. Getting Started logo image not showing up on Stackblitz - saving changes (leading to forked stackblitz) breaks static asset image serving stackblitz/webcontainer-core#493
9. alpha.2 ?
10. Issue Tracking
    • migrate more of our usages of path => new URL, more of a chore, and could be done post - ESM Configuration Tracking #824
    • We should really just try and make [more / all of Greenwood async] - make Greenwood CLI and plugins async through and through #823
      • first because bonus, the async variants of fs methods can take an instance of URL natively, so we wouldn't have to use pathToFileURL. Also, await will automatically wrap return values in Promise, so in that way async is backwards compatible, unlike a sync version. Also we should probably use more for ... in and less reduce 😵
    • ESM Config Files (i.e. not having to use .cjs as the config extension) - might need a tracking issue
      • stylelint config - Move to ESM stylelint/stylelint#5291 , https://github.com/stylelint/postcss-css-in-js/issues/225
      • ESLint config) - Implement Flat Config eslint/eslint#13481
      • Also, ESLint does not support TLA yet or import.meta
      • import json support in NodesJS in cli/src/index.js for reading package.json
      • PostCSS - (requires two postcss config files for now) - ES module support postcss/postcss-cli#387
      • CosmicConfig (underlying dep) - support mjs extensions out of box cosmiconfig/cosmiconfig#224
      • Babel - Support for ESM style Babel config files, calling Babel in async fixed? babel/babel-loader#894
    • Had to fallback to require for require.resolve.paths, does there exist a similar convention for ESM, e.g. import.meta.resolve.paths - ESM Configuration Tracking #824
    • Run tests in parallel? - will track on my own
11. Blog post - release v0.20.0 blog post #825

[thescientist13]

Cool, so testing for additional use cases is also working

npx ✅

"Home Page Test"

npx @greenwood/cli develop

Serve and Custom config (requires package.json, FYI)

npx @greenwood/cli serve

init ✅

Now It works!

my-app % npx @greenwood/init@latest --yarn
Need to install the following packages:
  @greenwood/init@latest
Ok to proceed? (y) y
-------------------------------------------------------
Initialize Greenwood Template ♻️
-------------------------------------------------------
Yarn Enabled
Initialzing project with files...
Creating manifest (package.json)...
Installing project dependencies...
yarn install v1.22.11
info No lockfile found.
[1/4] 🔍  Resolving packages...
warning @greenwood/cli > markdown-toc > gray-matter > coffee-script@1.12.7: CoffeeScript on NPM has moved to "coffeescript" (no hyphen)
warning @greenwood/cli > markdown-toc > remarkable > autolinker > gulp-header@1.8.12: Removed event-stream from gulp-header
[2/4] 🚚  Fetching packages...
[3/4] 🔗  Linking dependencies...
[4/4] 🔨  Building fresh packages...
success Saved lockfile.
✨  Done in 15.92s.
Initializing new project complete!
owenbuckley@Owens-MBP-2 my-app % yarn why @greenwood/cli
yarn why v1.22.11
[1/4] 🤔  Why do we have the module "@greenwood/cli"...?
[2/4] 🚚  Initialising dependency graph...
[3/4] 🔍  Finding dependency...
[4/4] 🚡  Calculating file sizes...
=> Found "@greenwood/cli@0.20.0-alpha.1"
info Has been hoisted to "@greenwood/cli"
info This module exists because it's specified in "devDependencies".
info Disk size without dependencies: "284KB"
info Disk size with unique dependencies: "272.23MB"
info Disk size with transitive dependencies: "306.19MB"
info Number of shared dependencies: 34
✨  Done in 0.65s.
owenbuckley@Owens-MBP-2 my-app % yarn serve
yarn run v1.22.11
$ greenwood serve
-------------------------------------------------------
Welcome to Greenwood (v0.20.0-alpha.1) ♻️
-------------------------------------------------------
Running Greenwood with the serve command.
Initializing project config
Initializing project workspace contexts
Generating graph of workspace files...
Started local development server at localhost:1984
Prerendering pages at http://127.0.0.1:1984
pages to render
 src/pages/index.md
 404.html
prerendering page... /
prerendering page... /404/
prerendering complete for page /.
prerendering complete for page /404/.
done prerendering all pages
copying file... .greenwood/graph.json
Initializing project config
Initializing project workspace contexts
Generating graph of workspace files...
Started production test server at localhost:8080

But because of #809 , user's are getting an ESM greenwood.config.js and package.json

% cat greenwood.config.js
export default {
  title: 'My Project'
};

% cat package.json
{
  "name": "my-app",
  "version": "1.0.0",
  "description": "",
  "type": "module",
  "scripts": {
    "start": "greenwood develop",
    "build": "greenwood build",
    "serve": "greenwood serve"
  },
  "devDependencies": {
    "@greenwood/cli": "^0.18.0"
  },
  "license": "ISC"
}

But are getting the older CJS version of Greenwood, which of course will fail

% npm ls @greenwood/cli
my-app@1.0.0 /Users/owenbuckley/Desktop/my-app
└── @greenwood/cli@0.18.0

owenbuckley@Owens-MBP-2 my-app % npm run start

> my-app@1.0.0 start /Users/owenbuckley/Desktop/my-app
> greenwood develop

-------------------------------------------------------
Welcome to Greenwood (v0.18.0) ♻️
-------------------------------------------------------
Running Greenwood with the develop command.
Initializing project config
Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: /Users/owenbuckley/Desktop/my-app/greenwood.config.js
require() of ES modules is not supported.
require() of /Users/owenbuckley/Desktop/my-app/greenwood.config.js from /Users/owenbuckley/Desktop/my-app/node_modules/@greenwood/cli/src/lifecycles/config.js is an ES module file as it is a .js file whose nearest parent package.json contains "type": "module" which defines all .js files in that package scope as ES modules.
Instead rename greenwood.config.js to end in .cjs, change the requiring code to use import(), or remove "type": "module" from /Users/owenbuckley/Desktop/my-app/package.json.

    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1085:13)
    at Module.load (internal/modules/cjs/loader.js:933:32)
    at Function.Module._load (internal/modules/cjs/loader.js:774:14)
    at Module.require (internal/modules/cjs/loader.js:957:19)
    at require (internal/modules/cjs/helpers.js:88:18)
    at /Users/owenbuckley/Desktop/my-app/node_modules/@greenwood/cli/src/lifecycles/config.js:57:29
    at new Promise ()
    at readAndMergeConfig (/Users/owenbuckley/Desktop/my-app/node_modules/@greenwood/cli/src/lifecycles/config.js:51:10)
    at /Users/owenbuckley/Desktop/my-app/node_modules/@greenwood/cli/src/lifecycles/compile.js:16:34
    at new Promise () {
  code: 'ERR_REQUIRE_ESM'
}

Simple solution for now, for this PR, is to just manually set the version in package.json in the init package template.

Stackblitz ✅

For some reason the logo image doesn't load when running npm start, but otherwise everything seems to be working as expected? (greenwood develop works finally locally if the git repo is cloned and run locally)

Note sure if at all related to either of these issues?

• Images are not loaded from local assets folder. stackblitz/webcontainer-core#208
• Images are not loaded from local assets folder (Engineblock) stackblitz/core#1687

---

Seems to be an issue with Stackblitz itself? I can reproduce even on the 0.19.0 version, and only when saving and having the blitz forked.