v0.31.0

Overview

This new minor release v0.31.0 focuses on greater ecosystem compatibility through a significant refactor of how import maps are generated and better handling of the exports map specification, as well as how node_modules are resolved generally. This includes libraries (Shoelace, Spectrum Web Components) as well as package managers like pnpm. The minimum version of NodeJS LTS was also bumped. (see the breaking changes section of the release notes).

# npm
$ npm i -D @greenwood/cli@latest

# Yarn 1.x (classic)
$ yarn upgrade @greenwood/cli@latest --dev

# pnpm
$ pnpm i -D @greenwood/cli@latest

Changelog

https://github.com/ProjectEvergreen/greenwood/issues?q=label%3Av0.31.0

1. improve support for package.json exports when building up import maps
2. leverage import.meta.resolve to support import maps generation and accurate node_modules resolution when building
3. walk package error if @spectrum-web-components/action-menu is installed even if not used
4. support non-JavaScript file formats for import maps
5. Improve PNPM support
6. Import Attributes support in Acorn
7. not all expected modern JavaScript syntax supported
8. leverage import.meta.resolve to support import maps generation and accurate node_modules resolution when building
9. Improve PNPM support
10. bare CSS @import specifiers are not resolving and bundling correctly
11. better document and clarify Lit SSR plugin usage caveats
12. frontmatter imports not working for any format supported by a resource plugin
13. ESM only configuration for PostCSS plugin
14. standardize on Greenwood config as single source for prerender behavior for all renderer plugins
15. CSS bundling optimization not handling transitive relative url(...) references
16. update init scaffolding to use unified website Discord link
17. unable to resolve packages with a nested package.json
18. intermittent Response.clone: Body has already been consumed error from the dev server
19. frontmatter content breaking graph data parsing in SSR pages
20. none optimization setting leads to broken resource requests in production builds
21. getting a Cannot read properties of null (reading 'rawAttrs') error
22. data client not working on production builds (when not using prerender option)
23. PostCSS plugin breaks bundling of SSR CSS-based import attributes
24. SSR pages are not have resource plugin optimization lifecycles applied
25. Upgrade minimum NodeJS LTS version
26. bundling for CSS relative node_modules based url references breaks
27. migrate to register function for NodeJS custom imports
28. allow for customizable serverless nodejs runtime version for Vercel adapter
29. Better support for (GitHub flavored) Markdown
30. fix missing runtime key for API routes when using Vercel adapter
31. import map generation not finding package.json for some libraries like tslib (when recursively segmenting entry point)
32. rollup bundling failing trying to resolve directories
33. log when API routes are being bundled
34. import map generation cache and dedupe optimizations
35. export map sub condition object keys with a wildcard are not resolving in the browser (condition not getting expanded)
36. better sanitize Rollup importer for when resolving user workspace resources
37. escaped HTML entities in markdown content are not being honored when prerendering Light DOM HTML
38. improve import map generation diagnostics
39. bump to latest version of puppeteer
40. upgrade to WCC v0.16.0

Breaking Changes

NodeJS version

The new minimum versions for NodeJS are as follows

• ^18.20.5
• ^20.10.0
• ^22.12.0

Import Maps (during development)

With this new version of Greenwood, our honoring of the exports spec will now be a lot more compliant and complete, but may (unintentionally) "break" some packages you might be using. In particular, one case observed where this breaks is Lit v2, which as of v3, now supports exports.

If you find any issues after upgrading, please review any diagnostics emitted by Greenwood and review the docs on our website, or check to see if there are newer versions of your package available. If you're still stuck, please reach out to us on Discord or in this GitHub discussion.

Markdown

As part of this release, we update all unified related plugins to latest. This introduced a couple user-facing breaking changes:

1. The markdown.settings configuration option option is longer supported as it's no longer supported by remark-parse
2. GFM (GitHub flavored markdown) was removed from remark, so make sure to bring your own, like remark-gfm, especially for things like tables

process.env.NODE_ENV

Prior to this release, Greenwood had included a behavior that would automatically replace instances of process.env.NODE_ENV in browser build output, but this was mostly for libraries like Redux that were not properly isomorphic. (process is not supported in browsers!)

Ideally packages you use should acknowledge this already, but if you still run into packages that make this assumption, you can re-recreate this substitution behavior using a Greenwood plugin

// greenwood.config.js
import { ResourceInterface } from '@greenwood/cli/src/lib/resource-interface.js';

class ProcessEnvReplaceResource extends ResourceInterface {
  constructor(compilation) {
    super();

    this.compilation = compilation;
  }

  async shouldIntercept(url) {
    // your custom condition goes here
    return url.pathname.endsWith('redux.mjs');
  }

  async intercept(url, request, response) {
    const body = await response.text();
    const env = process.env.__GWD_COMMAND__ === 'develop' ? 'development' : 'production';
    const contents = body.replace(/process.env.NODE_ENV/g, `"${env}"`);

    return new Response(contents, {
      headers: new Headers({
        'Content-Type': 'text/javascript',
      })
    });
  }
}

export default {
  // ...
  plugins: [{
    type: 'resource',
    name: 'process-env-replace',
    provider: (compilation) => new ProcessEnvReplaceResource(compilation)
  }]
}

WCC

There were a couple minor breaking changes in WCC, so please review the release notes to account for any changes that may impact your usage.

Node Modules

Going forward, the recommended pattern for referencing assets from your node_modules folder (that are not bare module ESM specifiers) will be to start all paths with /node_modules/. This will ensure Greenwood knows to use import.meta.resolve to find and lookup your dependency where ever it is installed based on your package managers.

Examples

@import "/node_modules/font-awesome/css/font-awesome.css";
@import "/node_modules/bootstrap/dist/css/bootstrap.css";

<script type="module" src="/node_modules/@shoelace-style/shoelace/dist/shoelace.js"></script>

PostCSS Plugin

Greenwo...

v0.31.0-alpha.6

Overview

This pre-release in the v0.31.0 fixes a few bug with Rollup bundling and import map generation, and also updates some dependencies. This is anticipated to be the last RC before a final GA release.

You can find the top-level tracking issue for this release here and if you have any questions, please feel free to reach out in Discord in the Greenwood #general channel.

To test the alpha, either manually bump all the versions in your package.json or you can use your package manager to upgrade each of your Greenwood dependencies to the alpha line (either way, all Greenwood dependencies need to be one the same version).

# npm
$ npm i @greenwood/cli@alpha

# Yarn 1.x (classic)
$ yarn upgrade @greenwood/cli@alpha

# pnpm
$ pnpm i @greenwood/cli@alpha

Changelog

https://github.com/ProjectEvergreen/greenwood/issues?q=label%3Av0.31.0+label%3Aalpha.6

1. export map sub condition object keys with a wildcard are not resolving in the browser (condition not getting expanded)
2. better sanitize Rollup importer for when resolving user workspace resources
3. escaped HTML entities in markdown content are not being honored when prerendering Light DOM HTML
4. improve import map generation diagnostics
5. bump to latest version of puppeteer
6. upgrade to WCC v0.16.0

Breaking Changes

WCC

There were a couple minor breaking changes in WCC, so please review the release notes to account for any changes that may impact your usage.

Known Issues

N / A

Diff

v0.31.0-alpha.5...v0.31.0-alpha.6

v0.31.0-alpha.5

Overview

This pre-release in the v0.31.0 fixes a bug with Rollup bundling and fixes some bugs and makes some enhancements for import map generation.

You can find the top-level tracking issue for this release here and if you have any questions, please feel free to reach out in Discord in the Greenwood #general channel.

To test the alpha, either manually bump all the versions in your package.json or you can use your package manager to upgrade each of your Greenwood dependencies to the alpha line (either way, all Greenwood dependencies need to be one the same version).

# npm
$ npm i @greenwood/cli@alpha

# Yarn 1.x (classic)
$ yarn upgrade @greenwood/cli@alpha

# pnpm
$ pnpm i @greenwood/cli@alpha

Changelog

https://github.com/ProjectEvergreen/greenwood/issues?q=label%3Av0.31.0+label%3Aalpha.5

1. import map generation not finding package.json for some libraries like tslib (when recursively segmenting entry point)
2. rollup bundling failing trying to resolve directories
3. log when API routes are being bundled
4. import map generation cache and dedupe optimizations

Breaking Changes

N / A

Known Issues

1. In some cases Rollup bundling may fail on invalid URL

Diff

v0.31.0-alpha.4...v0.31.0-alpha.5

v0.31.0-alpha.4

Overview

This pre-release in the v0.31.0 addresses a known issue with the previous pre-release.

You can find the top-level tracking issue for this release here and if you have any questions, please feel free to reach out in Discord in the Greenwood #general channel.

To test the alpha, either manually bump all the versions in your package.json or you can use your package manager to upgrade each of your Greenwood dependencies to the alpha line (either way, all Greenwood dependencies need to be one the same version).

# npm
$ npm i @greenwood/cli@alpha

# Yarn 1.x (classic)
$ yarn upgrade @greenwood/cli@alpha

# pnpm
$ pnpm i @greenwood/cli@alpha

Changelog

https://github.com/ProjectEvergreen/greenwood/issues?q=label%3Av0.31.0+label%3Aalpha.4

1. fix missing runtime key for API routes when using Vercel adapter

Breaking Changes

N / A

Known Issues

N / A

Diff

v0.31.0-alpha.3...v0.31.0-alpha.4

v0.31.0-alpha.3

Overview

This pre-release in the v0.31.0 updates the minimum NodeJS LTS version and adopts the new "register" API for custom loaders. There were additional updates for markdown dependencies and customizing the Vercel adapter runtime.

You can find the top-level tracking issue for this release here and if you have any questions, please feel free to reach out in Discord in the Greenwood #general channel.

To test the alpha, either manually bump all the versions in your package.json or you can use your package manager to upgrade each of your Greenwood dependencies to the alpha line (either way, all Greenwood dependencies need to be one the same version).

# npm
$ npm i @greenwood/cli@alpha

# Yarn 1.x (classic)
$ yarn upgrade @greenwood/cli@alpha

# pnpm
$ pnpm i @greenwood/cli@alpha

Changelog

https://github.com/ProjectEvergreen/greenwood/issues?q=label%3Av0.31.0+label%3Aalpha.3

1. Upgrade minimum NodeJS LTS version
2. bundling for CSS relative node_modules based url references breaks
3. migrate to register function for NodeJS custom imports
4. allow for customizable serverless nodejs runtime version for Vercel adapter
5. Better support for (GitHub flavored) Markdown

Breaking Changes

NodeJS version

The new minimum versions for NodeJS are as follows

• ^18.20.5
• ^20.10.0
• ^22.12.0

Custom Loaders

Custom loaders now use the register API and requires at least NodeJS ^20.10.0 or ^22.12.0 and using the --import flag

# before
$ node --loader ./node_modules/@greenwood/cli/src/loader.js ./node_modules/@greenwood/cli/src/index.js <command>

# after
$ node --import @greenwood/cli/src/register.js ./node_modules/@greenwood/cli/src/index.js <command>

Vercel Adapter

In addition to allowing the runtime of serverless functions to be configurable, the default version of NodeJS set will be 20.x

Markdown

As part of this release, we update all unified related plugins to latest. This introduced a couple user-facing breaking changes:

1. The markdown.settings configuration option option is longer supported as it's no longer supported by remark-parse
2. GFM (GitHub flavored markdown) was removed from remark, so make sure to bring your own, like remark-gfm, especially for things like tables

Known Issues

1. vercel adapter failing for API routes

Diff

v0.31.0-alpha.2...v0.31.0-alpha.3

v0.31.0-alpha.2

Overview

This pre-release in the v0.31.0 resolves a bunch of bug fixes and edge cases, as well as normalizing the relationship the prerender configuration setting with renderer plugins.

You can find the top-level tracking issue for this release here and if you have any questions, please feel free to reach out in Discord in the Greenwood #general channel.

To test the alpha, either manually bump all the versions in your package.json or you can use your package manager to upgrade each of your Greenwood dependencies to the alpha line (either way, all Greenwood dependencies need to be one the same version).

# npm
$ npm i @greenwood/cli@alpha

# Yarn 1.x (classic)
$ yarn upgrade @greenwood/cli@alpha

# pnpm
$ pnpm i @greenwood/cli@alpha

Changelog

https://github.com/ProjectEvergreen/greenwood/issues?q=label%3Av0.31.0+label%3Aalpha.2

1. standardize on Greenwood config as single source for prerender behavior for all renderer plugins
2. CSS bundling optimization not handling transitive relative url(...) references
3. update init scaffolding to use unified website Discord link
4. unable to resolve packages with a nested package.json
5. intermittent Response.clone: Body has already been consumed error from the dev server
6. frontmatter content breaking graph data parsing in SSR pages
7. none optimization setting leads to broken resource requests in production builds
8. getting a Cannot read properties of null (reading 'rawAttrs') error
9. data client not working on production builds (when not using prerender option)
10. PostCSS plugin breaks bundling of SSR CSS-based import attributes
11. SSR pages are not have resource plugin optimization lifecycles applied

Breaking Changes

prerender configuration and renderer plugins

Although Greenwood has a "top-level" configuration setting for prerender in greenwood.config.js, some renderer plugins also exposed a prerender option through their plugin configuration. As per #1343 , having multiple options for the same thing is confusing, additionally since there can only ever be one renderer at a time, so it's not like there is an option to mix and match.

So going forward, prerender configuration must be explicitly set in your greenwood.config.js. All relevant Greenwood plugins will just ignore the option if passed in to a plugins options.

Known Issues

1. bundling for CSS relative node_modules based url references breaks
   • As a workaround for now, you can use the "shortcut" alias, e.g. /node_modules/path/to/thing

Diff

v0.31.0-alpha.1...v0.31.0-alpha.2

v0.31.0-alpha.1

Overview

This second pre-release in the v0.31.0 line wraps up the first half of the work done in our previous alpha release of overhauling how Greenwood generates import maps and resolves node_modules dependencies, to better support the entire NodeJS exports map spec as well as play nicer with a variety of package managers (like PNPM) and their various location strategies of where node_modules are installed on disk. We also shipped a couple of bug fixes.

You can peek this repo to see using PNPM in a Greenwood project, with links to other branches with demos for Shoelace, Spectrum Web Components, and the USWDS!

You can find the top-level tracking issue for this release here and if you have any questions, please feel free to reach out in Discord in the Greenwood #general channel.

To test the alpha, either manually bump all the versions in your package.json or you can use your package manager to upgrade each of your Greenwood dependencies to the alpha line (either way, all Greenwood dependencies need to be one the same version).

# npm
$ npm i @greenwood/cli@alpha

# Yarn 1.x (classic)
$ yarn upgrade @greenwood/cli@alpha

# pnpm
$ pnpm i @greenwood/cli@alpha

Changelog

https://github.com/ProjectEvergreen/greenwood/issues?q=label%3Av0.31.0+label%3Aalpha.1

1. leverage import.meta.resolve to support import maps generation and accurate node_modules resolution when building
2. Improve PNPM support
3. bare CSS @import specifiers are not resolving and bundling correctly
4. better document and clarify Lit SSR plugin usage caveats
5. frontmatter imports not working for any format supported by a resource plugin
6. ESM only configuration for PostCSS plugin

Breaking Changes

Node Modules

Going forward, the recommended pattern for referencing assets from your node_modules folder (that are not bare module ESM specifiers) will be to start all paths with /node_modules/. This will ensure Greenwood knows to use import.meta.resolve to find and lookup your dependency where ever it is installed based on your package managers.

Examples

@import "/node_modules/font-awesome/css/font-awesome.css";
@import "/node_modules/bootstrap/dist/css/bootstrap.css";

<script type="module" src="/node_modules/@shoelace-style/shoelace/dist/shoelace.js"></script>

PostCSS Plugin

Greenwood know supports only needing to have one PostCSS config for your project. So with this release, you can now

1. Rename postcss.config.mjs -> postcss.config.js
2. Delete postcss.config.cjs

If you're using Storybook, rename your postcss.config.cjs -> .postcssrc.js instead

Known Issues

1. Discord link in init scaffolding output is using an expired link
2. ESM-only PostCSS config seems to not play well with Storybook - ProjectEvergreen/www.greenwoodjs.dev#145
3. The Lit SSR plugin is currently outputting some console.log messages, but that will be cleared up as part of

Diff

v0.31.0-alpha.0...v0.31.0-alpha.1

v0.31.0-alpha.0

Overview

This first pre-release in the v0.31.0 line introduces part 1 of an overhaul to how Greenwood generates import maps and resolves node_modules dependencies, to better support the entire exports spec as well as play nicer with a variety of package managers (like PNPM) and their various location strategies of where node_modules are installed on disk. In addition, these changes unlock more capabilities in import maps like referencing CSS files.

Be aware this is WIP and might break certain development and production build workflows, so please refrain from upgrading unless you are OK with testing and providing any compatibility feedback.

You can find the top-level tracking issue for this release here and if you have any questions, please feel free to reach out in Discord in the Greenwood #general channel.

To test the alpha, either manually bump all the versions in your package.json or you can use your package manager to upgrade each of your Greenwood dependencies to the alpha line (either way, all Greenwood dependencies need to be one the same version).

# npm
$ npm i @greenwood/cli@alpha

# Yarn 1.x (classic)
$ yarn upgrade @greenwood/cli@alpha

# pnpm
$ pnpm i @greenwood/cli@alpha

Changelog

https://github.com/ProjectEvergreen/greenwood/issues?q=label%3Av0.31.0+label%3Aalpha.0

1. improve support for package.json exports when building up import maps
2. leverage import.meta.resolve to support import maps generation and accurate node_modules resolution when building
3. walk package error if @spectrum-web-components/action-menu is installed even if not used
4. support non-JavaScript file formats for import maps
5. Improve PNPM support
6. Import Attributes support in Acorn
7. not all expected modern JavaScript syntax supported

Breaking Changes

Import Maps (during development)

With this new version of Greenwood, our use of the exports spec will now be a lot more compliant and complete, but may (unintentionally) "break" some packages you might be using. In particular, one case observed where this breaks is Lit v2, which as of v3, now supports exports.

If you find any issues after upgrading, please review any diagnostics emitted by Greenwood or check to see if there are newer versions of your package available.

process.env.NODE_ENV

Prior to this release, Greenwood had included a behavior that would automatically replace instances of process.env.NODE_ENV in browser build output, but this was mostly for libraries like Redux that were not properly isomorphic. (process is not supported in browsers!)

Ideally packages you use should acknowledge this already, but if you still run into packages that make this assumption, you can re-recreate this substitution behavior using a Greenwood plugin

// greenwood.config.js
import { ResourceInterface } from '@greenwood/cli/src/lib/resource-interface.js';

class ProcessEnvReplaceResource extends ResourceInterface {
  constructor(compilation) {
    super();

    this.compilation = compilation;
  }

  async shouldIntercept(url) {
    // your custom condition goes here
    return url.pathname.endsWith('redux.mjs');
  }

  async intercept(url, request, response) {
    const body = await response.text();
    const env = process.env.__GWD_COMMAND__ === 'develop' ? 'development' : 'production';
    const contents = body.replace(/process.env.NODE_ENV/g, `"${env}"`);

    return new Response(contents, {
      headers: new Headers({
        'Content-Type': 'text/javascript',
      })
    });
  }
}

export default {
  // ...
  plugins: [{
    type: 'resource',
    name: 'process-env-replace',
    provider: (compilation) => new ProcessEnvReplaceResource(compilation)
  }]
}

Known Issues

Import Maps (during development)

1. Seeing an interesting diagnostic report worth investigating here - ProjectEvergreen/www.greenwoodjs.dev#146

PNPM

As acknowledged, this is a very preliminary alpha release and will require a follow up alpha release (alpha.1) to completely flesh out full support for PNPM to completely un-hardcode the assumed location of node_modules on disk which will likely impact your production builds at this time, so please reserve bug reports until after our next alpha release.

Diff

v0.30.2...v0.31.0-alpha.0

v0.30.2

Overview

A couple more post release enhancements coming out of the v0.30.0 release.

Changelog

https://github.com/ProjectEvergreen/greenwood/issues?q=label%3Av0.30.2

1. sync additional peerDependencies on the Greenwood CLI for plugins
2. set shamefully-hoist pnpm flag in .npmrc for init scaffolding

Breaking Changes

N / A

Known Issues

N / A

Diff

v0.30.1...v0.30.2

v0.30.1

Overview

The v0.30.1 addresses a handful of reported issues found post launch of the v0.30.0 release.

Changelog

https://github.com/ProjectEvergreen/greenwood/issues?q=label%3Av0.30.1

1. table of contents sometimes missing first heading tag
2. @greenwood/init fails when no args are provided
3. bump all plugins peerDependencies to match latest minor release range - thanks @lschierer 🙌
4. new website cutover and docs refresh
5. TypeScript plugin not honoring default servePage setting when additional options are provided
6. fix sample code in PostCSS plugin README.md to use correct case sensitive name - thanks @lschierer 🙌

Breaking Changes

N / A

Known Issues

N / A

Diff

v0.30.0...v0.30.1