From a71ae8a9a1f106c317e015d5f42f3a1c2bef1812 Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Mon, 4 Nov 2024 13:37:05 -0500 Subject: [PATCH 01/16] cutover and refresh root README --- README.md | 59 ++++++++++++++++++++++++------------------------------- 1 file changed, 26 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 1f4b15cd0..af93aa63b 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,51 @@ # Greenwood [![Netlify Status](https://api.netlify.com/api/v1/badges/6758148c-5c38-44d8-b908-ca0a1dad0f7c/deploy-status)](https://app.netlify.com/sites/elastic-blackwell-3aef44/deploys) [![GitHub release](https://img.shields.io/github/tag/ProjectEvergreen/greenwood.svg)](https://github.com/ProjectEvergreen/greenwood/tags) -![GitHub Actions status](https://github.com/ProjectEvergreen/greenwood/workflows/Master%20Integration/badge.svg) -[![GitHub issues](https://img.shields.io/github/issues-pr-raw/ProjectEvergreen/greenwood.svg)](https://github.com/ProjectEvergreen/greenwood/issues) [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/ProjectEvergreen/greenwood/master/LICENSE.md) -[![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org/) ## Overview -**Greenwood** is your _workbench for the web_; focused on supporting modern web standards and development to help you create your next project. For information on getting started, reviewing our docs, or to learn more about the project and how it works, please [visit our website](https://www.greenwoodjs.io/). + +**Greenwood** is your _workbench for the web_, embracing web standards from the ground up to empower your stack from front to back. For information on getting started, reviewing our docs, or to learn more about the project and how it works, please [visit our website](https://www.greenwoodjs.dev/). Features: -- ⚡ [No bundle development](https://www.greenwoodjs.io/about/how-it-works/). Pages are built on the fly. -- 📝 HTML (and markdown) first [authoring experience](https://www.greenwoodjs.io/docs/layouts/) and ESM friendly. -- 🎁 [Optimized](https://www.greenwoodjs.io/docs/configuration/#optimization) production builds. -- 🚫 No JavaScript by default. -- 📖 Prerendering support for Web Components. -- ⚒️ Extensible via [plugins](https://www.greenwoodjs.io/plugins/). -- ⚙️ Supports [SSG, MPA, SPA, and SSR project types](https://www.greenwoodjs.io/docs/layouts/). (or a hybrid!) +- ⚡ No bundle development. Pages are built on the fly +- 📝 HTML first authoring experience and ESM friendly +- 📖 Server rendering and prerendering support for Web Components +- 📚 Build with friends like Lit, Tailwind and HTMX +- 🎁 Deploy self-hosted or to platforms like Vercel and Netlify +- ⚒️ Extensible via plugins +- ⚙️ Supports SSG, MPA, SPA, SSR and hybrid project types. Including API Routes. -> Greenwood is currently working towards a [1.0 release](https://github.com/ProjectEvergreen/greenwood/milestone/3). If you're interested in learning more about the web and web development (at any skill level!), or interested in checking out our high level roadmap and how Greenwood got where it is today, you can read our [State of GreenwoodJS blog post](https://www.greenwoodjs.io/blog/state-of-greenwood-2022/). We would love to have your help making Greenwood! ✌️ +> Greenwood is currently working towards a [1.0 release](https://github.com/ProjectEvergreen/greenwood/milestone/3). We would love to have your help building Greenwood! ✌️ ## Getting Started -Our website has a complete [Getting Started](http://www.greenwoodjs.io/getting-started) section that will walk you through creating a Greenwood project from scratch. -You can follow along with, or clone and go, the [companion repo](https://github.com/ProjectEvergreen/greenwood-getting-started). +Our website has a complete [Getting Started](http://www.greenwoodjs.dev/guides/getting-started/) guide that will walk you through creating a Greenwood project from scratch. + +You can follow along with, or clone and go, the [companion repo](https://github.com/ProjectEvergreen/greenwood-getting-started) or try it out live on [Stackblitz](https://stackblitz.com/github/projectevergreen/greenwood-getting-started). ## Installation + Greenwood can be installed with your favorite JavaScript package manager. + ```bash # npm -npm install @greenwood/cli --save-dev +npm i -D @greenwood/cli # yarn yarn add @greenwood/cli --dev + +# pnpm +pnpm add -D @greenwood/cli ``` -Then in your _package.json_, add the `type` field and `scripts` for the CLI, like so: +Then in your _package.json_, add the `type` field and `scripts` for the CLI: ```json { "type": "module", "scripts": { "build": "greenwood build", - "start": "greenwood develop", + "dev": "greenwood develop", "serve": "greenwood serve" } } @@ -49,27 +53,16 @@ Then in your _package.json_, add the `type` field and `scripts` for the CLI, lik - `greenwood build`: Generates a production build of your project - `greenwood develop`: Starts a local development server for your project -- `greenwood serve`: Generates a production build of your project and runs it on a NodeJS based web server +- `greenwood serve`: Runs a production server for a production build ## Documentation -All of our documentation is on our [website](https://www.greenwoodjs.io/) (which itself is built by Greenwood!). See our website documentation to learn more about: -- Configuration -- Pages -- Templates -- Component Model -- Styles and Assets -## Contributing -We would love your [contribution](.github/CONTRIBUTING.md) to Greenwood! Please check out our issue tracker for "good first issue" labels or feel to reach out to us on [Slack](https://join.slack.com/t/thegreenhouseio/shared_invite/enQtMzcyMzE2Mjk1MjgwLTU5YmM1MDJiMTg0ODk4MjA4NzUwNWFmZmMxNDY5MTcwM2I0MjYxN2VhOTEwNDU2YWQwOWQzZmY1YzY4MWRlOGI) in the room _"Greenwood"_ or on [Twitter](https://twitter.com/PrjEvergreen). +All of our documentation is on our [website](https://www.greenwoodjs.dev/), which [itself](https://github.com/ProjectEvergreen/www.greenwoodjs.dev) is built by Greenwood. -## Built With Greenwood -| Site | Repo | Project Details | -|-------|-------|------------------| -| [The Greenhouse I/O](https://www.thegreenhouse.io/) | [thegreenhouseio/www.thegreenhouse.io](https://github.com/thegreenhouseio/www.thegreenhouse.io) | Personal portfolio / blog website for @thescientist13 (Greenwood maintainer). | -| [Contributary](https://www.contributary.community/) | [ContributaryCommunity/www.contributary.community](https://github.com/ContributaryCommunity/www.contributary.community) | A website (SPA) for browsing open source projects that are open to contributions. Built with Lit and hosted with AWS (S3 / CloudFront). | -| [Analog Studios](https://www.analogstudios.net/) | [AnalogStudiosRI/www.analogstudios.net](https://github.com/AnalogStudiosRI/www.analogstudios.net) | A local music studio SPA website, originally written in Angular 2, recently migrated to Lit. It is currently transitioning to a [hybrid static + serverless website](https://github.com/AnalogStudiosRI/www.analogstudios.net/discussions/37) showing off the full potential of Greenwood and Web Components. Follow along for all the fun! 🤘 | +## Contributing -> Built a site with Greenwood? Open a PR and add it here! +We would love your [contribution](.github/CONTRIBUTING.md) to Greenwood! To get involved, you can check out our issue tracker for the ["good first issue" label](https://github.com/ProjectEvergreen/greenwood/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22), reach out to us on [Discord](https://discord.gg/bsy9jvWh), or start a discussion in our [GitHub repo](https://github.com/ProjectEvergreen/www.greenwoodjs.dev). ## License + See the [LICENSE](LICENSE.md) file for license rights and limitations (MIT). From 55513d79cd75f20133f2e15fabc9a75795935834 Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Mon, 4 Nov 2024 13:37:23 -0500 Subject: [PATCH 02/16] cutover and refresh CLI README --- packages/cli/README.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/packages/cli/README.md b/packages/cli/README.md index 150858c6d..90148803d 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -1,31 +1,39 @@ # @greenwood/cli ## Overview -CLI package for Greenwood. For more information and complete docs, please visit the [Greenwood website](https://www.greenwoodjs.io/docs). + +CLI package for Greenwood. For more information and complete docs, please visit the [Greenwood website](https://www.greenwoodjs.dev). ## Installation -You can use your favorite JavaScript package manager to install this package. -_examples:_ +Greenwood can be installed with your favorite JavaScript package manager. + ```bash # npm -npm install @greenwood/cli --save-dev +npm i -D @greenwood/cli # yarn yarn add @greenwood/cli --dev + +# pnpm +pnpm add -D @greenwood/cli ``` ## Usage -Then in your _package.json_, add the `type` field and `scripts` for the CLI like so: + +Then in your _package.json_, add the `type` field and `scripts` for the CLI: + ```json { "type": "module", "scripts": { "build": "greenwood build", - "start": "greenwood develop" + "dev": "greenwood develop", + "serve": "greenwood serve" } } ``` -- `npm run build`: generates a static build of your project -- `npm start`: starts a local development server for your project \ No newline at end of file +- `greenwood build`: Generates a production build of your project +- `greenwood develop`: Starts a local development server for your project +- `greenwood serve`: Runs a production server for a production build \ No newline at end of file From 2c9fb7d448b22f7771657f15d7714dbe916dd00f Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Mon, 4 Nov 2024 13:37:47 -0500 Subject: [PATCH 03/16] cutover and refresh init package contents --- packages/init/README.md | 75 ++++--------------- .../init/src/template/src/pages/index.html | 6 +- 2 files changed, 17 insertions(+), 64 deletions(-) diff --git a/packages/init/README.md b/packages/init/README.md index c6a82f497..646bb14a8 100644 --- a/packages/init/README.md +++ b/packages/init/README.md @@ -2,28 +2,28 @@ ## Overview -Init package for scaffolding out a new Greenwood project. For more information and complete docs, please visit the [Greenwood website](https://www.greenwoodjs.io/docs). +Init package for scaffolding out a new Greenwood project. For more information and complete docs, please visit the [Greenwood website](https://www.greenwoodjs.dev). ## Usage -Run the `init` command to scaffold a minimal Greenwood project into a directory of your choosing. +Run the `init` command to scaffold a minimal Greenwood project. ```bash -# providing an output directory of my-app -npx @greenwood/init@latest my-app +$ npx @greenwood/init@latest ``` -This will then output your project files into a directory called _my-app_ +This will then output your project files into a directory called _my-app_: + ```bash -my-app -├── .gitignore -├── greenwood.config.js -├── package.json -└── src/ - └─ ... +./ + .gitignore + greenwood.config.js + package.json + src/ + # ... ``` -## API +## Options ### Project Name @@ -31,52 +31,5 @@ By providing a name as the first argument, the `init` command will output the pr ```bash # example -npx @greenwood/init@latest my-app -``` - -> _Omitting my-app will install project files into the current directory._ - -### Template - -To scaffold your new project based on one of [Greenwood's starter templates](https://github.com/orgs/ProjectEvergreen/repositories?q=greenwood-template-&type=all&language=&sort=), pass the `--template` flag and then follow the prompts to complete the scaffolding. - -```bash -# example -npx @greenwood/init@latest --template - -------------------------------------------------------- -Initialize Greenwood Template ♻️ -------------------------------------------------------- -? Which template would you like to use? (Use arrow keys) -❯ blog -``` - -You can also pass the template you want from the CLI as well. -```bash -# example -npx @greenwood/init@latest --template=blog -``` - -### NPM Install - -To automatically run `npm install` after scaffolding, pass the `--install` flag. - -```bash -# example -npx @greenwood/init@latest --install -``` - -### Yarn Install - -To automatically run `yarn install` after scaffolding, pass the `--yarn` flag. - -```bash -# example -npx @greenwood/init@latest --yarn -``` - -> _Flags can be chained together!_ -> ```sh -> # This will use Yarn, install dependencies, and scaffold from the blog template -> $ npx @greenwood/init@latest --template --yarn --install -> ``` \ No newline at end of file +$ npx @greenwood/init@latest my-app +``` \ No newline at end of file diff --git a/packages/init/src/template/src/pages/index.html b/packages/init/src/template/src/pages/index.html index a519f44b2..dc446c5fe 100644 --- a/packages/init/src/template/src/pages/index.html +++ b/packages/init/src/template/src/pages/index.html @@ -78,17 +78,17 @@

Edit src/pages/index.html to start making changes

Getting Started

-

Follow our guide on learning Greenwood for the first time.

+

Follow our guide on learning Greenwood for the first time.

Docs

-

Learn about Greenwood's features and capabilities.

+

Learn about Greenwood's features and capabilities.

Guides

-

Walkthroughs on ways to build and deploy with Greenwood.

+

Walkthroughs on ways to build and deploy with Greenwood.

From 327bb7c44c0f2f78753a549ea67945b155bf5df6 Mon Sep 17 00:00:00 2001 From: Owen Buckley Date: Mon, 4 Nov 2024 20:46:40 -0500 Subject: [PATCH 04/16] cutover and refresh plugin READMEs --- packages/cli/README.md | 8 +- packages/plugin-adapter-netlify/README.md | 24 ++++-- packages/plugin-adapter-vercel/README.md | 21 +++-- packages/plugin-babel/README.md | 29 ++++--- packages/plugin-css-modules/README.md | 18 +++-- packages/plugin-google-analytics/README.md | 23 +++--- packages/plugin-graphql/README.md | 26 +++---- packages/plugin-import-commonjs/README.md | 23 +++--- packages/plugin-import-jsx/README.md | 19 +++-- packages/plugin-import-raw/README.md | 14 ++-- packages/plugin-include-html/README.md | 30 ++++++- packages/plugin-polyfills/README.md | 20 +++-- packages/plugin-postcss/README.md | 16 ++-- packages/plugin-renderer-lit/README.md | 23 +++--- packages/plugin-renderer-puppeteer/README.md | 82 ++++++++++---------- packages/plugin-typescript/README.md | 4 +- 16 files changed, 219 insertions(+), 161 deletions(-) diff --git a/packages/cli/README.md b/packages/cli/README.md index 90148803d..c5d943fd9 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -2,7 +2,7 @@ ## Overview -CLI package for Greenwood. For more information and complete docs, please visit the [Greenwood website](https://www.greenwoodjs.dev). +CLI package for Greenwood. For more information and complete docs on Greenwood, please visit [our website](https://www.greenwoodjs.dev). ## Installation @@ -10,13 +10,13 @@ Greenwood can be installed with your favorite JavaScript package manager. ```bash # npm -npm i -D @greenwood/cli +$ npm i -D @greenwood/cli # yarn -yarn add @greenwood/cli --dev +$ yarn add @greenwood/cli --dev # pnpm -pnpm add -D @greenwood/cli +$ pnpm add -D @greenwood/cli ``` ## Usage diff --git a/packages/plugin-adapter-netlify/README.md b/packages/plugin-adapter-netlify/README.md index 9b6c3bfb2..0280a2635 100644 --- a/packages/plugin-adapter-netlify/README.md +++ b/packages/plugin-adapter-netlify/README.md @@ -1,13 +1,14 @@ # @greenwood/plugin-adapter-netlify ## Overview -This plugin enables usage of the [Netlify](https://www.netlify.com/) platform for hosting a Greenwood application. + +This plugin enables usage of the [Netlify](https://www.netlify.com/) platform for hosting a Greenwood application. For more information and complete docs on Greenwood, please visit [our website](https://www.greenwoodjs.dev). > This package assumes you already have `@greenwood/cli` installed. ## Features -In addition to publishing a project's static assets to the Netlify CDN, this plugin adapts Greenwood [API routes](https://www.greenwoodjs.io/docs/api-routes/) and [SSR pages](https://www.greenwoodjs.io/docs/server-rendering/) into Netlify [Serverless functions](https://docs.netlify.com/functions/overview/) using their [custom build](https://docs.netlify.com/functions/deploy/?fn-language=js#custom-build-2) approach +In addition to publishing a project's static assets to the Netlify CDN, this plugin adapts Greenwood [API routes](https://www.greenwoodjs.io/docs/api-routes/) and [SSR pages](https://www.greenwoodjs.io/docs/server-rendering/) into Netlify [Serverless functions](https://docs.netlify.com/functions/overview/) using their [custom build](https://docs.netlify.com/functions/deploy/?fn-language=js#custom-build-2) approach. This plugin will automatically generate a custom [__redirects_](https://docs.netlify.com/routing/redirects/) file to correctly map your SSR page and API route URLs to the corresponding Netlify function endpoint (as a rewrite). You can continue to customize your Netlify project using your _netlify.toml_ file as needed. @@ -15,15 +16,18 @@ This plugin will automatically generate a custom [__redirects_](https://docs.net ## Installation + You can use your favorite JavaScript package manager to install this package. -_examples:_ ```bash # npm -npm install @greenwood/plugin-adapter-netlify --save-dev +$ npm i -D @greenwood/plugin-adapter-netlify # yarn -yarn add @greenwood/plugin-adapter-netlify --dev +$ yarn add @greenwood/plugin-adapter-netlify --dev + +# pnpm +$ pnpm add -D @greenwood/plugin-adapter-netlify ``` @@ -45,13 +49,14 @@ Set the `AWS_LAMBDA_JS_RUNTIME` environment variable [in your Netlify UI](https: ## Usage -Add this plugin to your _greenwood.config.js_. + +Add this plugin to your _greenwood.config.js_: ```javascript import { greenwoodPluginAdapterNetlify } from '@greenwood/plugin-adapter-netlify'; export default { - ... + // ... plugins: [ greenwoodPluginAdapterNetlify() @@ -59,7 +64,9 @@ export default { } ``` -Optionally, your API routes will have access to Netlify's `context` object as the second parameter to the `handler` function. For example: +Optionally, your API routes will have access to Netlify's `context` object as the second parameter to the `handler` function. + +For example: ```js export async function handler(request, context = {}) { console.log({ request, context }); @@ -82,6 +89,7 @@ Then when you run it, you will be able to run and test a production build of you > _Please see caveats section for more information on this feature. 👇_ ## Caveats + 1. [Edge runtime](https://docs.netlify.com/edge-functions/overview/) is not supported ([yet](https://github.com/ProjectEvergreen/greenwood/issues/1141)). 1. Netlify CLI / Local Dev - [`context` object](https://docs.netlify.com/functions/create/?fn-language=js#code-your-function-2) not supported when running `greenwood develop` command diff --git a/packages/plugin-adapter-vercel/README.md b/packages/plugin-adapter-vercel/README.md index d8f3458a2..0e9692b2e 100644 --- a/packages/plugin-adapter-vercel/README.md +++ b/packages/plugin-adapter-vercel/README.md @@ -1,7 +1,8 @@ # @greenwood/plugin-adapter-vercel ## Overview -Enables usage of Vercel Serverless runtimes for API routes and SSR pages. + +Enables usage of [Vercel](https://vercel.com/) hosting for API routes and SSR pages. For more information and complete docs on Greenwood, please visit [our website](https://www.greenwoodjs.dev). > This package assumes you already have `@greenwood/cli` installed. @@ -13,18 +14,21 @@ In addition to publishing a project's static assets to the Vercel's CDN, this pl ## Installation + You can use your favorite JavaScript package manager to install this package. -_examples:_ ```bash # npm -npm install @greenwood/plugin-adapter-vercel --save-dev +$ npm i -D @greenwood/plugin-adapter-vercel # yarn -yarn add @greenwood/plugin-adapter-vercel --dev +$ yarn add @greenwood/plugin-adapter-vercel --dev + +# pnpm +$ pnpm add -D @greenwood/plugin-adapter-vercel ``` -You will then want to create a _vercel.json_ file, customized to match your project. Assuming you have an npm script called `build` +You will then want to create a _vercel.json_ file, customized to match your project. Assuming you have an npm script called `build`: ```json { "scripts": { @@ -33,7 +37,8 @@ You will then want to create a _vercel.json_ file, customized to match your proj } ``` -This would be the minimum _vercel.json_ configuration you would need +This would be the minimum _vercel.json_ configuration you would need: + ```json { "buildCommand": "npm run build" @@ -41,13 +46,14 @@ This would be the minimum _vercel.json_ configuration you would need ``` ## Usage + Add this plugin to your _greenwood.config.js_. ```javascript import { greenwoodPluginAdapterVercel } from '@greenwood/plugin-adapter-vercel'; export default { - ... + // ... plugins: [ greenwoodPluginAdapterVercel() @@ -55,7 +61,6 @@ export default { } ``` - ## Caveats 1. [Edge runtime](https://vercel.com/docs/concepts/functions/edge-functions) is not supported ([yet](https://github.com/ProjectEvergreen/greenwood/issues/1141)). 1. The Vercel CLI (`vercel dev`) is not compatible with Build Output v3. diff --git a/packages/plugin-babel/README.md b/packages/plugin-babel/README.md index 5996e6d29..c9522bce2 100644 --- a/packages/plugin-babel/README.md +++ b/packages/plugin-babel/README.md @@ -1,30 +1,35 @@ # @greenwood/plugin-babel ## Overview -A Greenwood plugin for using [**Babel**](https://babeljs.io/) and applying it to your JavaScript. + +A Greenwood plugin for using [**Babel**](https://babeljs.io/) and applying it to your JavaScript. For more information and complete docs on Greenwood, please visit [our website](https://www.greenwoodjs.dev). > This package assumes you already have `@greenwood/cli` installed. ## Installation + You can use your favorite JavaScript package manager to install this package. -_examples:_ ```bash # npm -npm install @greenwood/plugin-babel --save-dev +$ npm i -D @greenwood/plugin-babel # yarn -yarn add @greenwood/plugin-babel --dev +$ yarn add @greenwood/plugin-babel --dev + +# pnpm +$ pnpm add -D @greenwood/plugin-babel ``` ## Usage -Add this plugin to your _greenwood.config.js_. + +Add this plugin to your _greenwood.config.js_: ```javascript import { greenwoodPluginBabel } from '@greenwood/plugin-babel'; export default { - ... + // ... plugins: [ greenwoodPluginBabel() @@ -32,7 +37,7 @@ export default { } ``` -Create a _babel.config.cjs_ in the root of your project with your own custom plugins / settings that you've installed and want to use. +Create a _babel.config.cjs_ in the root of your project with your own custom plugins / settings that you've installed and want to use: ```javascript module.exports = { @@ -48,18 +53,12 @@ This will then process your JavaScript with Babel using the configured plugins a > _For now Babel configuration needs to be in CJS. Will we be adding ESM support soon!_ ## Options + This plugin provides a default _babel.config.js_ that includes support for [**@babel/preset-env**](https://babeljs.io/docs/en/babel-preset-env) using [**browserslist**](https://github.com/browserslist/browserslist) with reasonable [default configs](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/plugin-babel/src/) for each. If you would like to use it, either standalone or with your own custom _babel.config.js_, you will need to take the following extra steps: -1. Install `@babel/runtime` and `regenerator-runtime` as direct dependencies of your project - ```bash - # npm - npm install @babel/runtime regenerator-runtime - - # yarn - yarn add @babel/runtime regenerator-runtime - ``` +1. Install `@babel/runtime` and `regenerator-runtime` as dependencies to your project 1. When adding `greenwoodPluginBabel` to your _greenwood.config.js_, enable the `extendConfig` option ```js import { greenwoodPluginBabel } from '@greenwood/plugin-babel'; diff --git a/packages/plugin-css-modules/README.md b/packages/plugin-css-modules/README.md index 8cabc12ae..16b8bc97b 100644 --- a/packages/plugin-css-modules/README.md +++ b/packages/plugin-css-modules/README.md @@ -4,7 +4,7 @@ A Greenwood plugin for authoring [**CSS Modules ™️**](https://github.com/css-modules/css-modules). It is a modest implementation of [the specification](https://github.com/css-modules/icss). 🙂 -This is NOT to be confused with [CSS Module _Scripts_](https://web.dev/articles/css-module-scripts), which Greenwood already supports. +This is NOT to be confused with [CSS Module _Scripts_](https://web.dev/articles/css-module-scripts), which Greenwood already supports. For more information and complete docs on Greenwood, please visit [our website](https://www.greenwoodjs.dev). > This package assumes you already have `@greenwood/cli` installed. @@ -12,24 +12,26 @@ This is NOT to be confused with [CSS Module _Scripts_](https://web.dev/articles/ You can use your favorite JavaScript package manager to install this package. -_examples:_ ```bash # npm -npm i -D @greenwood/plugin-css-modules +$ npm i -D @greenwood/plugin-css-modules # yarn -yarn add @greenwood/plugin-css-modules --dev +$ yarn add @greenwood/plugin-css-modules --dev + +# pnpm +$ pnpm add -D @greenwood/plugin-css-modules ``` ## Usage -Add this plugin to your _greenwood.config.js_. +Add this plugin to your _greenwood.config.js_: ```javascript import { greenwoodPluginCssModules } from '@greenwood/plugin-css-modules'; export default { - ... + // ... plugins: [ greenwoodPluginCssModules() @@ -37,7 +39,7 @@ export default { } ``` -Now you can create a CSS file that ends in _.module.css_ +Now you can create a CSS file that ends in _.module.css_: ```css /* header.module.css */ @@ -65,7 +67,7 @@ Now you can create a CSS file that ends in _.module.css_ ``` -And reference that in your (Light DOM) HTML based Web Component +And reference that in your (Light DOM) HTML based Web Component: ```js // header.js diff --git a/packages/plugin-google-analytics/README.md b/packages/plugin-google-analytics/README.md index 6554cdaa8..7fc196e54 100644 --- a/packages/plugin-google-analytics/README.md +++ b/packages/plugin-google-analytics/README.md @@ -1,28 +1,27 @@ # @greenwood/plugin-google-analytics ## Overview -A Greenwood plugin adding support for [Google Analytics](https://developers.google.com/analytics/) JavaScript tracker. It assumes you already have your own Tracking ID(s) and [can either filter out tracking for everything but your production environment](https://stackoverflow.com/a/1251931/417806) so that local testing doesn't interfere with production data, or use a conditional based `analyticsId` using an environment variable, ex. - -```js -const analyticsId = process.env.NODE_ENV === 'xxx' ? 'UA-123...' : 'UA-345...'; -``` - -> _For more information and complete docs about Greenwood, please visit the [Greenwood website](https://www.greenwoodjs.io/)._ +A Greenwood plugin adding support for [Google Analytics](https://developers.google.com/analytics/) JavaScript tracker. It assumes you already have your own Tracking ID(s) and [can either filter out tracking for everything but your production environment](https://stackoverflow.com/a/1251931/417806) so that local testing doesn't interfere with production data, or use a conditional based `analyticsId` using an environment variable. For more information and complete docs on Greenwood, please visit [our website](https://www.greenwoodjs.dev). +> This package assumes you already have `@greenwood/cli` installed. ## Installation + You can use your favorite JavaScript package manager to install this package. This package assumes you already have `@greenwood/cli` installed. -_examples:_ ```bash # npm -npm install @greenwood/plugin-google-analytics --save-dev +$ npm i -D @greenwood/plugin-google-analytics # yarn -yarn add @greenwood/plugin-google-analytics --dev +$ yarn add @greenwood/plugin-google-analytics --dev + +# pnpm +$ pnpm add -D @greenwood/plugin-google-analytics ``` ## Usage + Use this plugin in your _greenwood.config.js_ and pass in your Google Analytics ID, which can either be a * Measurement ID (**recommended**): ex. `G-XXXXXX` * Tracking ID (legacy): ex. `UA-XXXXXX` @@ -31,7 +30,7 @@ Use this plugin in your _greenwood.config.js_ and pass in your Google Analytics import { greenwoodPluginGoogleAnalytics } from '@greenwood/plugin-google-analytics'; export default { - ... + // ... plugins: [ greenwoodPluginGoogleAnalytics({ @@ -46,10 +45,12 @@ This will then add the Google Analytics [JavaScript tracker snippet](https://dev > _Learn more about [Measurement and Tracking IDs](https://support.google.com/analytics/answer/9539598)_. ## Options + - `analyticsId` (required) - Your Google Analytics ID - `anonymous` (optional) - Sets if tracking of IPs should be done anonymously. Default is `true` ### Outbound Links + For links that go outside of your domain, the global function [`getOutboundLink`](https://support.google.com/analytics/answer/7478520) is available for you to use. Example: diff --git a/packages/plugin-graphql/README.md b/packages/plugin-graphql/README.md index fb136e301..56fc5bec9 100644 --- a/packages/plugin-graphql/README.md +++ b/packages/plugin-graphql/README.md @@ -2,14 +2,14 @@ ## Overview -A plugin for Greenwood to support using [GraphQL](https://graphql.org/) to query Greenwood's [content graph](https://www.greenwoodjs.io/docs/data/) with our optional [pre-made queries](https://www.greenwoodjs.io/docs/data/#data-client). It runs [**apollo-server**](https://www.apollographql.com/docs/apollo-server/) on the backend at build time and provides a **"read-only"** [**@apollo/client** _"like"_](https://www.apollographql.com/docs/react/api/core/ApolloClient/#ApolloClient.readQuery) interface for the frontend that you can use. +A plugin for Greenwood to support using [GraphQL](https://graphql.org/) to query Greenwood's [content graph](https://www.greenwoodjs.io/docs/data/) with our optional [pre-made queries](https://www.greenwoodjs.io/docs/data/#data-client). It runs [**apollo-server**](https://www.apollographql.com/docs/apollo-server/) on the backend at build time and provides a **"read-only"** [**@apollo/client** _"like"_](https://www.apollographql.com/docs/react/api/core/ApolloClient/#ApolloClient.readQuery) interface for the frontend that you can use. For more information and complete docs on Greenwood, please visit [our website](https://www.greenwoodjs.dev). > This package assumes you already have `@greenwood/cli` installed. ## Caveats As of now, this plugin requires some form of [prerendering](https://www.greenwoodjs.io/docs/server-rendering/#render-vs-prerender) either through: -1. Enabling [custom imports](https://www.greenwoodjs.io/docs/server-rendering/#custom-imports) or +1. Enabling [custom imports](https://www.greenwoodjs.io/docs/server-rendering/#custom-imports), or 1. Installing the [Puppeteer renderer plugin](https://github.com/ProjectEvergreen/greenwood/tree/master/packages/plugin-renderer-puppeteer). ## Installation @@ -18,10 +18,13 @@ You can use your favorite JavaScript package manager to install this package. ```bash # npm -npm install @greenwood/plugin-graphql --save-dev +$ npm i -D @greenwood/plugin-graphql # yarn -yarn add @greenwood/plugin-graphql --dev +$ yarn add @greenwood/plugin-graphql --dev + +# pnpm +$ pnpm add -D @greenwood/plugin-graphql ``` ## Usage @@ -122,9 +125,7 @@ The Graph query returns an array of all pages. import client from '@greenwood/plugin-graphql/src/core/client.js'; import GraphQuery from '@greenwood/plugin-graphql/src/queries/graph.gql'; -. -. -. +// async connectedCallback() { super.connectedCallback(); @@ -144,9 +145,7 @@ Based on [our Collections feature](http://www.greenwoodjs.io/docs/data/#collecti import client from '@greenwood/plugin-graphql/src/core/client.js'; import CollectionQuery from '@greenwood/plugin-graphql/src/queries/collection.gql'; -. -. -. +// ... async connectedCallback() { super.connectedCallback(); @@ -169,9 +168,7 @@ This will return a set of pages under a specific route and is akin to using [`ge import client from '@greenwood/plugin-graphql/src/core/client.js'; import ChildrenQuery from '@greenwood/plugin-graphql/src/queries/children.gql'; -. -. -. +// ... async connectedCallback() { super.connectedCallback(); @@ -200,7 +197,8 @@ query { } ``` -Or within your component +Or within your component: + ```javascript import gql from 'graphql-tag'; // comes with Greenwood diff --git a/packages/plugin-import-commonjs/README.md b/packages/plugin-import-commonjs/README.md index 216f7c83c..c02baa994 100644 --- a/packages/plugin-import-commonjs/README.md +++ b/packages/plugin-import-commonjs/README.md @@ -1,30 +1,36 @@ # @greenwood/plugin-import-commonjs ## Overview -A plugin for Greenwood for loading CommonJS based modules (`require` / `module.exports`) in the browser using ESM (`import` / `export`) syntax. _**Note**: It is highly encouraged that you favor ESM based packages for the cleanest / fastest interop and developer experience. Additional processing time and dependencies are required to handle the conversion._ + +A plugin for Greenwood for loading CommonJS based modules (`require` / `module.exports`) in the browser using ESM (`import` / `export`) syntax. For more information and complete docs on Greenwood, please visit [our website](https://www.greenwoodjs.dev). + +_**Note**: It is highly encouraged that you favor ESM based packages for the cleanest / fastest interop and developer experience. Additional processing time and dependencies are required to handle the conversion._ > This package assumes you already have `@greenwood/cli` installed. ## Installation You can use your favorite JavaScript package manager to install this package. -_examples:_ ```bash # npm -npm install @greenwood/plugin-import-commonjs --save-dev +$ npm i -D @greenwood/plugin-import-commonjs # yarn -yarn add @greenwood/plugin-import-commonjs --dev +$ yarn add @greenwood/plugin-import-commonjs --dev + +# pnpm +$ pnpm add -D @greenwood/plugin-import-commonjs ``` ## Usage -Add this plugin to your _greenwood.config.js_ and spread the `export`. + +Add this plugin to your _greenwood.config.js_: ```javascript import { greenwoodPluginImportCommonJs } from '@greenwood/plugin-import-commonjs'; export default { - ... + // ... plugins: [ greenwoodPluginImportCommonJs() @@ -32,14 +38,13 @@ export default { } ``` -This will then allow you to use a CommonJS based modules in the browser. For example, here is how you could use [**lodash**](https://lodash.com/) (although as mentioned above, in this case, you would want to use [**lodash-es**](https://www.npmjs.com/package/lodash-es) instead.) +This will then allow you to use a CommonJS based modules in the browser. For example, here is how you could use [**lodash**](https://lodash.com/) (although as mentioned above, in this case, you would want to use [**lodash-es**](https://www.npmjs.com/package/lodash-es) instead) ```javascript //