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. enhancement/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. docs/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 are using. For example, Redux used to have NodeJS specific APIs in its client bundles, but as of the 5.x release, they now correctly segment browser from Node bundles using exports, which Greenwood will now honor.

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

v0.30.0

Overview

The v0.30.0 release is here! Please check out our blog post to learn about some of the new features now available.

Changelog

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

1. Isolation Mode
2. Lit v3 Upgrade and SSR Enhancements
3. Single File Bundles (SFBs) for SSR pages and API routes - thanks @DevLab2425 🙌
4. Upgrade Rollup (and friends) to 3.x - thanks @DevLab2425 🙌
5. CSS and JSON import attributes
6. support bundling of url properties (like for @font-face + src) during CSS file optimization
7. Layouts (Templates) and Pages
8. support all CSS function pseudo classes / elements for CSS optimizing
9. Sitemap Generation (static) (thanks @jstockdi 🙌 )
10. improve naming for (nested) bundled SSR page and API route entry points to better reflect original file based routing name](#1226)
11. nested SSR pages (and API routes) are throwing a module not found error (needs additional patch for adapters)
12. "real" production import attributes
13. CSS optimization workflow parity during development
14. attributes for frontmatter imports
15. polyfill configurations for import maps and attributes
16. improve init package scaffolding baseline starting point
17. livereload not reloading on SVG (image) file changes consistently
18. CSS Nesting Support
19. HTML Web Components
20. CSS Modules ™️ plugin
21. Content as Data

Breaking Changes

Minimum NodeJS Version

The new minimum NodeJS version for Greenwood is now v18.20.0. Make sure to update your CI and hosting scripts accordingly.

Layouts

The templates/ directory has now re-named to the layouts/ directory. This includes your frontmatter.

# before
src/
  templates/
    app.html

# after
src/
  layouts/
    app.html

API Routes

API routes have now been nested under the pages/ directory to better emphasis the shared routing of file based routing for pages, as the URLs all end up in the same "namspace" anyway

# before
src/
  api/
    search.js

# after
src/
  pages/
    api/
      search.js

Important

Don't forget to update any references to any relative ESM imports in your API routes.

Custom Imports

This now means that using custom imports no longer requires the experimental flag, though a flag is still needed

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

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

Note

We hope that before our 1.0 release this flag will not be required.

Active Frontmatter

The activeFrontmatter configuration setting has been renamed to activeContent and now enabled with it all the related Content as Data feature set. The old interpolateFrontmatter behavior is still there, and now additional frontmatter is has been exposed to users. The full list includes

• id
• route
• title
• label
• data
• tableOfContents (which is Array<Object{ label, route }>

Menus

Menus have been renamed / re-implemented as Collections and their usage for GraphQL users will need to be updated to adopt that convention.

In general, these will the steps you will need to take:

1. Frontmatter

   <!-- before -->
   ---
   menu: navigation
   ---
   
   <!-- after -->
   ---
   collection: navigation
   order: 1
   ---

2. MenuQuery will need to be renamed to CollectionQuery and you will pass a name instead of menu property

   // before
   import MenuQuery from '@greenwood/plugin-graphql/src/queries/menu.gql';
   
   const response = await client.query({
     query: MenuQuery,
     variables: {
       menu: 'navigation'
     }
   });
   
   const navigation = response.data.menu.children.map(item => item.item);
   
   // after
   import CollectionQuery from '@greenwood/plugin-graphql/src/queries/collection.gql';
   
   const response = await client.query({
     query: CollectionQuery,
     variables: {
       name: 'navigation'
     }
   });
   
   this.navigation = response.data.collection;

Polyfills (Import Maps / Import Attributes)

Import Maps

As Import Maps are now pretty widely supported by browser, their polyfilling has been disabled by default. To enable this for development (only), add this configuration to your greenwood.config.js

export default {
  polyfills: {
    importMaps: true
  }
}

Import Attributes

As Import Attributes (CSS, JSON) are not widely supported across all browsers, an option has been added to greenwood.config.js if you want Greenwood to polyfill these behaviors (essentially inlining the modules contents as a default export.

export default {
  polyfills: {
    importAttributes: ['css', 'json'] // choose which ones you want polyfilled
  }
}

Import CSS / JSON Plugin deprecations

Now that loading CSS and JSON are web standards, the following plugins will no longer be recieving updates and will be deprecated as part of this release.

• plugin-import-css
• plugin-import-json

Import Raw

However, if you still need to load arbitrary content as an ES Module like the CSS plugin provided, there is now a general purpose plugin called plugin-import-raw which can provided this functionality, e.g.

/* my-component.css */
h1 {
  color: red;
}

import styles from './my-component.css?type=raw'`;

console.log(styles); // h1 { color: red; }

Tip

If you were using these plugins within something like WTR, you'll want to modify your customizations accordingly by making sure to pass the Sec-Fetch-Dest header. See this file for reference.

Lit Renderer Plugin

The Lit Renderer has a few breaking changes to be aware of

1. You must use the getBody API (Custom Elements as Pages are not support with Lit)
2. The compatible version of Lit is now v3
3. You'll want to use isolation mode for your API routes (in particular when using greenwood serve as it is also the default for SSR pages)

See a working example here

Known Issues

1. Import CSS / JSON plugins not showing as deprecated
2. TypeScript plugin not working with servePage and additional options
3. npx @greenwood/init failing when no custom directory provided

Diff

v0.29.4...v0.30.0

v0.30.0-alpha.8

Overview

This release in the v0.30.0 line fixes a couple bugs related to Lit SSR support with import maps, and addressing some misleading prompts in the init scaffolding command.

In progress docs available here. Full release blog will come out with the final release.

If using Yarn, you can can upgrade all your Greenwood packages at once

$ yarn upgrade --scope @greenwood --latest

Changelog

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

1. init scaffolding can give misleading / broken next steps instructions
2. ensure Lit SSR hydration script loads after importmaps

Breaking Changes

N / A

Known Issues

N / A

Diff

v0.30.0-alpha.7...v0.30.0-alpha.8

v0.30.0-alpha.7

Overview

This release in the v0.30.0 release introduces a robust set of "Content as Data" APIs for Greenwood, a CSS Modules ™️ plugin, support for HTML (Light DOM) Web Components, and added the ability for the init to create a directory.

In progress docs available here. Full release blog will come out with the final release.

If using Yarn, you can can upgrade all your Greenwood packages at once

$ yarn upgrade --scope @greenwood --latest

Changelog

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

1. CSS Nesting Support
2. add initial directory option for init scaffolding
3. HTML Web Components
4. CSS Modules ™️ plugin
5. Content as Data

Breaking Changes

Active Frontmatter

The activeFrontmatter configuration setting has been renamed to activeContent and now enabled with it all the related Content as Data feature set. The old interpolateFrontmatter behavior is still there, and now additional frontmatter is has been exposed to users. The full list includes

• id
• route
• title
• label
• data
• tableOfContents (which is Array<Object{ label, route }>

Menus

Menus have been renamed / re-implemented as Collections and their usage for GraphQL users will need to be updated to adopt that convention.

In general, these will the steps you will need to take:

1. Frontmatter

   <!-- before -->
   ---
   menu: navigation
   ---
   
   <!-- after -->
   ---
   collection: navigation
   order: 1
   ---

2. MenuQuery will need to be renamed to CollectionQuery and you will pass a name instead of menu property

   // before
   import MenuQuery from '@greenwood/plugin-graphql/src/queries/menu.gql';
   
   const response = await client.query({
     query: MenuQuery,
     variables: {
       menu: 'navigation'
     }
   });
   
   const navigation = response.data.menu.children.map(item => item.item);
   
   // after
   import CollectionQuery from '@greenwood/plugin-graphql/src/queries/collection.gql';
   
   const response = await client.query({
     query: CollectionQuery,
     variables: {
       name: 'navigation'
     }
   });
   
   this.navigation = response.data.collection;

Known Issues

1. init scaffolding can give misleading / broken next steps instructions
2. ensure Lit SSR hydration script loads after importmaps

Diff

v0.30.0-alpha.6...v0.30.0-alpha.7

v0.30.0-alpha.6

Overview

This release in the v0.30.0 release introduces a new configuration flag for enabling the polyfilling of import maps or import attributes, and refreshed the starting contents of the @greenwood/init scaffolding package.

In progress docs available here. Full release blog will come out with the final release.

If using Yarn, you can can upgrade all your Greenwood packages at once

$ yarn upgrade --scope @greenwood --latest

Changelog

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

1. polyfill configurations for import maps and attributes
2. improve init package scaffolding baseline starting point
3. refine standard CSS plugin intercepting
4. provide initialized compilation to custom loader script (and resource plugins)
5. livereload not reloading on SVG (image) file changes consistently

Breaking Changes

Polyfills (Import Maps / Import Attributes)

Import Maps

As Import Maps are now pretty widely supported by browser, their polyfilling has been disabled by default. To enable this for development (only), add this configuration to your greenwood.config.js

export default {
  polyfills: {
    importMaps: true
  }
}

Import Attributes

As Import Attributes (CSS, JSON) are not widely supported across all browsers, an option has been added to greenwood.config.js if you want Greenwood to polyfill these behaviors (essentially inlining the modules contents as a default export.

export default {
  polyfills: {
    importAttributes: ['css', 'json'] // choose which ones you want polyfilled
  }
}

Known Issues

N / A

Diff

v0.30.0-alpha.5...v0.30.0-alpha.6

v0.30.0-alpha.5

Overview

This release in the v0.30.0 release improves handling of CSS Modules (Constructable Stylesheets bundling), add support for providing attributes to frontmatter imports, and brings CSS optimization / bundling parity to the development workflow.

In progress docs available here. Full release blog will come out with the final release.

If using Yarn, you can can upgrade all your Greenwood packages at once

$ yarn upgrade --scope @greenwood --latest

Changelog

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

1. real production import attributes
2. CSS optimization workflow parity during development
3. attributes for frontmatter imports

Breaking Changes

N / A

Known Issues

1. Standard CSS bundling handling non CSS files
2. Race condition with inline optimization and bundling Constructable Stylesheets

Diff

v0.30.0-alpha.4...v0.30.0-alpha.5