projectevergreen / greenwood Goto Github PK

Greenwood is your full-stack workbench for the web, focused on supporting modern web standards and development to help you create your next project.

Home Page: https://www.greenwoodjs.io

License: MIT License

JavaScript 93.08% CSS 1.77% HTML 4.88% Dockerfile 0.03% TypeScript 0.25%

webcomponents jamstack hacktoberfest nodejs javascript css html esm ssg ssr lit

greenwood's Introduction

Greenwood

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.

Features:

⚡ No bundle development. Pages are built on the fly.
📝 HTML (and markdown) first authoring experience and ESM friendly.
🎁 Optimized production builds.
🚫 No JavaScript by default.
📖 Prerendering support for Web Components.
⚒️ Extensible via plugins.
⚙️ Supports SSG, MPA, SPA, and SSR project types. (or a hybrid!)

Greenwood is currently working towards a 1.0 release. 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. We would love to have your help making Greenwood! ✌️

Getting Started

Our website has a complete 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.

Installation

Greenwood can be installed with your favorite JavaScript package manager.

# npm
npm install @greenwood/cli --save-dev

# yarn
yarn add @greenwood/cli --dev

Then in your package.json, add the type field and scripts for the CLI, like so:

{
  "type": "module",
  "scripts": {
    "build": "greenwood build",
    "start": "greenwood develop",
    "serve": "greenwood serve"
  }
}

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

Documentation

All of our documentation is on our website (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 to Greenwood! Please check out our issue tracker for "good first issue" labels or feel to reach out to us on Slack in the room "Greenwood" or on Twitter.

Built With Greenwood

Site	Repo	Project Details
The Greenhouse I/O	thegreenhouseio/www.thegreenhouse.io	Personal portfolio / blog website for @thescientist13 (Greenwood maintainer).
Contributary	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	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 showing off the full potential of Greenwood and Web Components. Follow along for all the fun! 🤘

Built a site with Greenwood? Open a PR and add it here!

License

See the LICENSE file for license rights and limitations (MIT).

greenwood's People

Contributors

Stargazers

Watchers

Forkers

orlundohubbard devanandgowda xk2600 hghmn danilocbueno loki1205 thiago18andre devlab2425 jstockdi

greenwood's Issues

passing a custom publicPath breaks serialization

Type of Change

Summary

Passing a config with a custom publicPath doesn't result in a serialized HTML file

config

// (**note**: `devServer is required see: )
module.exports = {
  publicPath: '/owen',
  devServer: {
    port: 1981,
    host: 'localhost'
  }
};

index.html

<!-- cat public/index.html -->
<body>

    <eve-app></eve-app>

  <script type="text/javascript" src="/owen/index.861cad5fddf22530b046.bundle.js"></script>

should be something like

<body>

    <eve-app><!---->
        <lit-route path="/hello" component="eve-hello" class="style-scope eve-app"><!----><!----></lit-route>
				<lit-route path="/" component="eve-index" class="style-scope eve-app" active=""><!----><!----><eve-index class="style-scope lit-route"><!---->
      <div class="wrapper style-scope eve-index">
        <div class="eve-index content style-scope">
          <wc-md-index class="style-scope eve-index"><!---->

      <div class="style-scope wc-md-index">
        <h3 class="style-scope wc-md-index">Greenwood</h3>
<p class="style-scope wc-md-index">This is the home page built by Greenwood. Make your own pages in src/pages/index.js!</p>

      </div>
      <!----></wc-md-index>
        </div>
      </div>
    <!----></eve-index><!----><!----></lit-route>

        <lit-route class="style-scope eve-app"><!----><!----></lit-route>
    <!----></eve-app>

Details

Serialization has regressed, likely when #53 was merged.

[RFC] Typings / TypeScript

Type of Change

Summary

For a build system like this, which is essentially a custom gluing together of various open source tools, and in turn building up a custom domain model of terms / objects like:

compilation
context
graph
scaffold
etc

One option is to document with something like JSDoc, another option is to use types. 😄

Details

Introducing a type system might really help add a lot of consistency and continuity to the project and since it's a command line tool, should hopefully obviate the need to have to do any transpiling, but would need to be runnable in a runtime that supports TS. (possibly using ts-node?)

Anyway, creating interface for things like compilation and context could go a long way towards hardening the build process and development / debugging easier.

[RFC] External Data (Graph) Sources

Type of Change

Summary

Need to figure out a way to pull in external data at build time and pull it in a build time. First POC should likely be with Wordpress. (Greenwood blog?)

Details

I think it should be pretty straight forward, expose a "Graph" Plugin type that gets read on build to extract the metadata and then just serves the route as any other would?

From there, other plugins could be built around that in follow up PRs, like for WordPress or Sanity support.

can't resolve CSS file with custom workspace

Type of Change

Summary

Trying to create a project with a custom page template and shared CSS file and getting a build error. (related to #80 )

$ yarn build
yarn run v1.12.3
$ yarn clean && node ./packages/cli/index.js build
$ rimraf ./**/.greenwood/** && rimraf ./**/public/** && rimraf ./coverage
-------------------------------------------------------
Welcome to Greenwood ♻️
-------------------------------------------------------
Reading project config
Initializing project workspace contexts
Generating graph of workspace files...
Scaffolding out project files...
Generate pages from templates...
Writing imports for md...
Writing Lit routes...
setup index page and html
Scaffolding complete.
Building project for production.
Building SPA from compilation...
./.greenwood/about/about.js
Module not found: Error: Can't resolve '../theme.css' in '/Users/owenbuckley/Workspace/project-evergreen/repos/greenwood/.greenwood/about'

Details

Workspace

www/
   pages/
     index.md
     about.md
    templates/ 
      page-template.js
    theme.css

Config

const path = require('path');

module.exports = {
  workspace: path.join(__dirname, 'www'),
  title: 'Greenwood',
  meta: [
    { property: 'og:site', content: 'greenwood' },
    { name: 'twitter:site', content: '@PrjEvergreen' }
  ]
};

Note: I wasn't able to reproduce in the build.default.workspace-template-page-style even after adding a pages/ directory with an index.md and about.md so I think it could be related to using a custom workspace?

As a user, I would like a CLI with a commander-like interface

Type of Change

Summary

We need a general cli script which also displays commands usage from a help menu.

Details

e.g.

--------------------------------------
---------- Greenwood-----------------
--------------------------------------

greenwood <command> 

greenwood build

greenwood dev

greenwood serve

greenwood --help

etc

As a developer, I would like unit tests

Unit testing for each addition will make it easy to know for sure if a new feature or bug fix breaks the overall build.

improve clarity / purpose of cli folder structure by renaming key files

Type of Change

Summary

Simply enough, our project has started to take shape, and I think some name changes are in order.

Details

change init.js to context.js since that's more specific to what's it doing
packages/cli/tasks -> commands/
packages/cli/lib -> lifecycles/
packages/cli/lib/util -> packages/cli/lib/

add advanced test cases / improve code coverage for build related tests

Type of Change

Summary

Continuing on from the work in #56 and some of the leftover TODOs from the #74 PR to add more test cases, for the sake of getting the re-org PR first to unblock other work.

Details

Would want to add additional test cases for:

Build w/ import in a page with custom front matter
Build with all custom templates (index, 404, app template, page template) and custom workspace
Build config w/custom workspace and nested pages
HTMLElement?
Get more coverage on build.js (error handling)

consolidate configuration and compilation objects

Type of Change

Summary

It might make sense to consolidate these two objects, to reduce the cumbersome nature of passing them around.

Note: this should only focus on internal configuration / refactoring. Have opened #40 for exposing userland APIs

Details

Consolidate config into compilation object
Update all references throughout the build pipeline
All tests should pass
Unify with webpack configuration per #33 (comment)
A number of TODOs raised discussed in #36
- publicPath
- userWorkspace, pagesDir in webpack configs
- config
- entry in webpack.config.develop.js

This will help clear a path forward for the following issues:

#30
#5
#32
others probably

As a user I would like a Home Page for the project

Type of Change

Summary

A home page for project, built by Greenwood. Should talks about the project with a basic theme and quick start usage guide.

Details

Configure the project with a www directory
Create basic header and footer components with LitElement
Create a template/app-template.js
Create a basic index.md with project overview and quick start

As a developer I would like to define custom page template types (in front matter)

Type of Change

Summary

(Not sure if this actually supported, but just in case)

Currently user's can provide a custom template for creating a page, by creating a src/templates/page-template.js.

It would be nice to provide (through front matter) a way to define a template at a per page level.

Details

Through front matter, a user could supply their own custom template, as long as the corresponding template is found in src/templates/.

ex.
src/templates/admin-template.js

import { html, LitElement } from 'lit-element';
MDIMPORT;

class AdminPageTemplate extends LitElement {
  render() {
    return html`
      <div class='wrapper'>
        <div class='admin-page-template content'>
          <entry></entry>
        </div>
      </div>
    `;
  }
}

customElements.define('admin-template', AdminPageTemplate);

src/pages/admin/index.md

---
path: '/admin'
label: 'admin'
template: 'admin'
---

### Admin Page

This is the admin page.

public root index file duplicate output

Type of Change

Summary

The index.html file is being outputted twice. Once to ./public/index.html (and it's not serialized) and then again to ./public/index/index.html (serialized).

This bug was reintroduced when we added nested directories and allowed the ability to add index files within nested routes. There used to be an exception within the renderer which would force the index.html of the public route to be created without creating any additional folder.

Details

Solution is simple. Just before the serialized html file is written, we add an exception for this single case:

browser.js

  // Exception for index file in root public directory
  const endOfPathFolder = target.substring(target.lastIndexOf('/'), target.length);
  const isRootPublicDirectoryException = endOfPathFolder === '/index';

  if (isRootPublicDirectoryException) {
    return await fs.writeFileSync(path.join(outputDirectory, 'index.html'), html);
  }

Polyfills plugin should feature detect polyfills support (using webcomponents loader)

Type of Change

Summary

Currently, polyfills are enabled by default. I think for a static site, as few dependencies should be needed, but if some are needed to support browsers, they should be opt-in, ideally through differential loading

Edit: we won't be implementing differential loading, instead we are using our evergreen build.

Details

Disable polyfills by default (this may not be possible right away, or may require coordinate work, see #193 )
Allow opt-in flag specifically for IE11 (es5 adapter?)
Support custom .browserslistrc (nice to have - new ticket?)
~~Write test cases for these use cases~~
~~Update README with documentation / samples of the above use cases~~
~~Looks like we'll need to migrate PostCSS~~
~~Use webcomponent-loader or everything? (but actually is bigger bundle size wise than just using bundle?)~~
~~Question: confirm which browsers actually need polyfills~~

passing absolute path for workspace config not reading from provided directory

Type of Change

Summary

Passing an absolute path in greenwood.config.js seems not to pick up any of the pages. See #80 for an example.

Details

Given the directory structure of #80

Even just making a couple pages, nothing works. Did I do something wrong?

$ yarn build
yarn run v1.12.3
$ yarn clean && node ./packages/cli/index.js build
$ rimraf ./**/.greenwood/** && rimraf ./**/public/** && rimraf ./coverage
-------------------------------------------------------
Welcome to Greenwood ♻️
-------------------------------------------------------
Reading project config
Initializing project workspace contexts
Generating graph of workspace files...
Scaffolding out project files...
Generate pages from templates...
Writing imports for md...
Writing Lit routes...
setup index page and html
Scaffolding complete.
Building project for production.
Building SPA from compilation...
webpack build complete
...................................
Static site generation complete!
...................................
✨  Done in 14.68s.
Owens-MBP-2:greenwood owenbuckley$ ls -l public/
total 152
-rw-r--r--  1 owenbuckley  staff    247 May 15 19:56 404.html
drwxr-xr-x  3 owenbuckley  staff     96 May 15 19:56 hello
-rw-r--r--  1 owenbuckley  staff  67262 May 15 19:56 index.a3ef5b33d622c65ad3fc.bundle.js
-rw-r--r--  1 owenbuckley  staff   3717 May 15 19:56 index.html

No About page
Index.html content is default Greenwood

As a developer I would like Greenwood to be Lighthouse compliant (not PWA)

Type of Change

Summary

Lighthouse is an auditing tool for measuring and benchmarking web applications and websites to make sure they are performant and following best practices.

Greenwood app shell by default should score as high as possible (90+) by default.

Details

Should score 90+ in the following categories

Performance
Best Practices
Accessibility

Should also have documentation somewhere about hosting best practices (gzip, HTTPS, HTTP/2) somewhere

As a user I should have a development mode to facilitate local development

Type of Change

Summary

Currently Greenwood only suports a straight production build, which obviously isn't all that helpful as a development tool. A development server and option should be created to provide a local development workflow for Greenwood.

Details

Enable developers to call greenwood with --develop flag
Should run all build steps instead of serialize
And should run webpack-dev-server instead (maybe create a lib/develop.js)
Update README documentation

release prep: clean up project README, add badges, npm publishing

Type of Change

Summary

Badges all quick summary status of various build / project activities

current release
build status
license

Details

Follow the example for CEA

Overview
Getting Started / Documentation
Project Goals / Roadmap
License
npm publishing -files, name, main, etc
Others?

As a user I would like auto detection of pages and template directories

Type of Change

Summary

Currently Greenwood is only aware of templates and pages in its own project. Not very helpful, obviously. The project should auto detect basic directories for the user and use the source files in those directories instead.

Details

Currently Greenwood knows of these directories

pagesDir: path.join(__dirname, './templates/'),
scratchDir: path.join(process.cwd(), './.greenwood/'),
templatesDir: path.join(__dirname, './templates/'),
publicDir: path.join(process.cwd(), './public')

What it should do instead

Is "auto-detect" these directories first
- pagesDir - src/pages/
- templatesDir - src/templates
Handle page as default template type
Should error gracefully with nice user feedback, e.g
- "It looks like you don't have a <app|page> template defined. Please include a simple example like this in <src/ ex. sample code here"
- "It looks like you don't
Greenwood should "own" index.html, we will make it more configurable in other tasks.
Write tests
Update README docs to demonstrate this new feature

As a user I should be able to use a global CSS file

Type of Change

Summary

All projects will inevitably require some CSS. At minimum, a file for a basic global CSS file should be supported.

Details

A default CSS file should be created in templates/ that should be built and imported into the final output
A user provided file in src/styles.css should be supported and bundled instead, if auto detected
Unit tests should be written for both cases above
Update README documentation to demonstrate the capabilities

Questions

Should this be supported in templates instead? Should we support both options?

As a user, I would like the ability to set and include custom favicons

Type of Change

Summary

At the moment, applications will have no favicon. I'd like the ability to add a favicon as well as a manifest of different sizes.

Details

The default index.html contains a commented out manifest.json. We can use the favicons webpack plugin to set the favicon in production, based on a specific path in user workspace, or a path within a configuration file value(leaning towards this).

greenwood.config.js

module.exports = {
    icon: path.join(__dirname, 'www', 'assets', 'icon.png')
}

lifecycles/config.js

defaultConfig: {
    iconPath: path.join(__dirname, 'src', 'assets', 'icon.png')
}

config/webpack.config.prod.js / common ?

plugins: [
  new FaviconsWebpackPlugin({
    // Your source logo
    logo: config.iconPath,
    // The prefix for all image files (might be a folder or a name)
    prefix: 'icons-[hash]/',
    // Emit all stats of the generated icons
    emitStats: false,
    // The name of the json containing all favicon information
    statsFilename: 'iconstats-[hash].json',
    // Generate a cache file with control hashes and
    // don't rebuild the favicons until those hashes change
    persistentCache: true,
    // Inject the html into the html-webpack-plugin
    inject: true,
    // favicon background color (see https://github.com/haydenbleasel/favicons#usage)
    background: '#fff',
    // favicon app title (see https://github.com/haydenbleasel/favicons#usage)
    title: 'Webpack App',

    // which icons should be generated (see https://github.com/haydenbleasel/favicons#usage)
    icons: {
      android: true,
      appleIcon: true,
      appleStartup: true,
      coast: false,
      favicons: true,
      firefox: true,
      opengraph: false,
      twitter: false,
      yandex: false,
      windows: false
    }
  })
]

Problem is, right now we aren't adding assets to /public only index files + bundle.

Also, maybe to increase configurability, we could enable the favicons object from the greenwood.config.js?

try / catch error handling in index.js returning undefined

Type of Change

Summary

This only seems to return undefined
https://github.com/ProjectEvergreen/greenwood/blob/master/packages/cli/index.js#L73

console.error(err.red);

Details

Probably because err.red doesn't exist on the passed in err param. Probably just needs to be wrapped in a string literal.

As a user I would like develop task to open default browser automatically

Type of Change

Summary

Tap into the existing webpack devServer to enable auto browser opening when running yarn develop

Details

Not sure the best option, but probably the [open](https://webpack.js.org/configuration/dev-server/#devserveropen command and pass it into greenwood.config.js (once #53 gets merged)

Have develop mode pick next randomly available port

Type of Change

Summary

By default, instead of hardcoding the port for devServer it might be really nice to have it just pick the next available port on the user's local machine?

Details

It seems like this possible with webpack-dev-server just by omitting port
https://stackoverflow.com/questions/42055201/webpack-dev-server-dynamic-port

[RFC] User Workspace Path Mapping

Type of Change

Summary

After having laid out some of the basic features and explored some of their implementation details:

Default Pages and Template Directory
Global CSS
Isolated CSS
Development Mode
Custom Assets
This comment, which echos some of the initial observations identified by @hutchgrant from the original Greenwood POC

I think though now we can define a higher level design that accounts for and can balance these various technical needs:

Building a static site from a users src/pages/ and src/templates directories
Providing a flexible user "workspace" / directory strucutre, e.g. src/*
- components
- assets
- styles
- etc
Orchestrating all that through the graphing / scaffolding phases, lockstepped to the webpack powered build phase

Solving this is important because webpack will only know of code that is specified through entry config, which right now requires an additional build steps before we can run it through webpack.

If we could use that scaffolded code, but also still respect paths to the user's source code, then we would have a pretty nice pipeline! This means we can also just use webpack-dev-server for the entire development stack too (I think) without any additional file watching, which would be awesome. (Though this should be confirmed, like when new pages are created, will webpack rebuild?)

Details

For example, given a user who provides their own page-template, and wants to import some global CSS

// user's src/templates/app-templates.js
import { html, LitElement } from 'lit-element';
import css from '../styles/global.css';
MDIMPORT

class PageTemplate extends LitElement {
  render() {
    return html`
      <style>
        ${css}
      </style

      <div class='wrapper'>
        <div class='page-template content'>
          <entry></entry>
        </div>
      </div>
    `;
  }
}

customElements.define('page-template', PageTemplate);

The issue is when the generated page is put into the scratchDir (./greenwood/), the import paths are now "out" of context, so to speak.
ex.

import { html, LitElement } from 'lit-element';
import css from '../templates/theme.css';  // this file will now 404
import './hello.md';

class PageTemplate extends LitElement {
  render() {
    return html`
      <style>
        ${css}
      </style

      <div class='wrapper'>
        <div class='eve-hello content'>
          <wc-md-hello></wc-md-hello>
        </div>
      </div>
    `;
  }
}

customElements.define('eve-hello', PageTemplate);

So at a high level, this RFC is hope hoping to solve:

A simple "API" for users
- pages/
- templates/
- that's it!
A flexible user workspace through import or @import
- components/
- assets/
- styles/
- whatever/!
Leverage webpack through and through for development and production
Provide a clear development path for the above referenced issues

Proposals

Here are a couple ideas I have:

Context Linking, aka "src"mapping

I'm hoping webpack can actually solve this entire problem in a simple way for us (I hope) by using the ContextReplacementPlugin

With this, we can tell webpack where to look when resolving paths so that Greendwood can dynamically look up and link to a user's entire project without needing to configure everything other than

pages/
templates/

Path Rewriting

Similar in spirit, this approach would literally rewrite paths in place. So given the example provided in the detail section, we could instead generate a page from a page template like this

import { html, LitElement } from 'lit-element';
import css from '/Users/path/to/project/repo/<dynamic>/global.css';
import '/Users/path/to/project/repo/src/pages/hello.md';

class PageTemplate extends LitElement {
  render() {
    return html`
      <style>
        ${css}
      </style

      <div class='wrapper'>
        <div class='eve-hello content'>
          <wc-md-hello></wc-md-hello>
        </div>
      </div>
    `;
  }
}

customElements.define('eve-hello', PageTemplate);

remove need to maintain prod and development versions of template files

Type of Change

Summary

Currently, there is a need to maintain two versions of files

index.html
404.html

It would be a nicer development experience if only one of each of these files was needed to server both purposes. I could see someone easily forgetting to update one, and not the other.

Details

In regards to #14 , specifically #36 (comment)

Also, remove usage of process.env.NODE_ENV

[RFC] Move page template scaffold to webpack wc-markdown-loader

Type of Change

Summary

This is a proposal(WIP), I do not have a working version, this is purely theory. I want to discuss the pros and cons and whether it's worth pursuing this idea because it will come with problems and benefits. It likely cannot be done in a single PR. We can try, but I imagine it will have consequences later that will have to be smoothed out.

Currently

.md files are loaded via wc-markdown-loader, they're built into web components and exported e.g. <wc-md-hello></wc-md-hello>.

A page template selected for each .md file(page-template.js by default) is then used to scaffold a new web component that contains that .md file exported component within scaffold.js. The newly scaffolded component is put in scratch directory and imported to app.js

Suggested changes

Remove writePageComponentFromTemplate() from scaffold.js and place it instead in the wc-markdown-loader. Using the graph, load the required template from within the loader and build using the template here.

We will then have to change the imports file list.js to use markdown files and not the scaffolded .js files within scratch directory.

Pros

assuming we can adjust import path context:

make global css much easier
make meta much easier
make page template styling easier(no additional shadow dom, no need to import duplicate css and render it within each individual md file as we currently are in mock-app)
may make live-reload in develop easier
may be more modular, more reliant on webpack loaders, making it easier to modularize for plugins etc in the future

Cons

we may not be able to adjust import path so that it's relative to user workspace
may encounter issues with list.js using markdown from the user workspace instead of js from scratch directory
may encounter issues with the current context replacement, which was tricky to setup

I'll update pros and cons on the list if you have any ideas or criticism here. It may not be worth the effort to do.

As a user / developer I should have verbose (and quiet) output logging

Type of Change

Summary

Logging can be very useful, as long as it can be controlled. In my mind, there should be two options minimum

"normal": output basic status / progress logging
"verbose": outputs more debug level logging, useful for CI and testing environments

Details

Provide a --verbose option that can be used to enable advanced logging capabilities
Introduce a logging library to toggle between info / debug vs. warning and error level logging
Add relevant logs where applicable, and at the appropriate level
Should include proper error logging / handling / process.exit
Update README with documentation on --verbose flag

webpack not displaying errors when running from node

Type of Change

Summary

When testing the project locally, running yarn build, errors being emitted by webpack seemed to get swallowed by node, even though error detection was added.

However, if running webpack from the CLI, the errors will display clearly.

./node_modules/.bin/webpack --config ./packages/cli/config/webpack.config.prod.js --progress

Details

By intentionally forcing an error in the webpack configuration (like a loader name mispelling)

Running yarn build should error and clearly break the build

[RFC] User Extensibility - Lifecycles and Plugins

Type of Change

Summary

Allowing users to extend functionality of the tool will be the best way to gain adoption and support. Things like lifecycles and plugins can provide consistent APIs and hooks for users to tap into the Greenwood build process and extend the functionality to support their project's needs.

Details

Some of these may be maintained by Greenwood itself, but would want to flesh out

~~Lifecycles: How and when are operations run (phases), and what's the inputs and outputs for each phase~~
Plugins: Extend the build phase by providing your own webpack plugins?

Full details mapped out here
#17 (comment)

Parallel Serialization

Type of Change

Summary

Currently the serialization phase runs serially, one page at a time, each page as a Promise.

const runBrowser = async (compilation) => {

  try {
    return await Promise.all(compilation.graph.map(({ route, label }) => {
      return browserRunner(`http://127.0.0.1:${PORT}${route}`, label, route, compilation.context.publicDir);
    }));
  } catch (err) {
    // eslint-disable-next-line no-console
    console.log(err);
    return false;
  }
};

It would be good to see what options there are to support running these in parallel so multiple pages could be serialized at once.

Otherwise this happens locally 😬

Details

Something to consider is how to manage the "firehose" of creating and serializing pages. It would probably make sense to support a queue so for very large applications, hundreds and thousands of pages won't get spun up at once and potentially stall / crash the build server or local development workstation.

It should probably be a configurable value from greenwood.config.js.

[RFC] Monorepo

Type of Change

Summary

lerna makes it easy to manage deployment and version control of multiple packages to the npm registry. Currently, there's a single package.json and it manages the overall project but we need a npm package.json for each individual package.

Details

We have the project almost setup for this with the packages folder structure, but we need to move the package.json to the cli package and run npx lerna init which will generate a new package.json and lerna.json file.

We also need to change paths of scripts within the package.json to be relative to the cli package folder, instead of what it is now in the root directory.

[RFC] Case based / BDD organization strategy for tests

Type of Change

Summary

As being discussed in #52 , it looks like there is a case to be made for having a deliberate plan to write, manage and organize unit tests as the project scales and more configuration / APIs become available and we don't create a giant single file of unit tests.

Also wort tracking this conversation about testing configuration / setup: #53 (review)

Details

In general, the main goals of this suggestion are to help address / solve some of the observed and encountered issues with growing out our unit tests

Reduce overlapping concerns / duplicate testing
Lack of clarity structure for how to setup, organize, and group tests
Ensure test run times are manageable
Provide confidence in good coverage of all key code / hot paths through unit testing

One project I've found that has a good approach to unit test build tools is webpack. They organize their tests by cases, which I think is a great paradigm for us, in terms of thinking but organization.

I propose we do something similar, with goal of having clearly articulated test cases that can avoid the need to have redundant tests and ensure tests can focus specifically on the features / changes they are meant to cover.

Cases could be based on packages maybe?

test/
  fixtures/  // same as it is now
  unit/   // if we want to unit tests individual files?
  cases/
    cli/
       build.default.spec.js   
       build.error-handling.spec.js
       build.nested-directories.js
       build.config.workspaace.spec.js
       build.config.dev-server.spec.js

Common things can still be done TestSetup still. Maybe there could be a way to ensure a common set of tests pass each time somehow? I think tests are an exception though when it comes to keeping things DRY.

Open to ideas, but I think at the very least the organizational aspect of something like this (not necessarily the technical aspects) will be very useful not only for us as maintainers, but also contributors.

Note: might be good to do this and #50 and #67 together

As a user I would like an (API) Documentation page for the project

Type of Change

Summary

Some documentation on how to use the project will be needed (naturally).

Details

Run through the basic of how to use the APIs, Configuration, workflows, etc for using Greenwood at a very technical level, as captured in the parent issue

Configuration - All options and what they mean
Markdown - Markdown for content, link to cheatsheet, examples
Component Model - How to use Web Components
Templates - Page and App Templates
Front Matter - Options and capabilities
Tech stack (aka "How It Works") - Insight into the technologies used?

This should very much be seen as a reference, and so should probably start with most common / used configuration and features first (configuration, page templates, front matter) and the more "advanced" stuff later, like app templates and component model.

As a user I should be able to use additional CSS from front matter

Type of Change

Summary

Related to #7 , a user should be able to define CSS in front-matter so that additional CSS files can be included by the user.

Details

Support default styles.css in the project's template/ directory

Support an API like

---
path: '/hello'
label: 'hello'
css: '/path/a.css'
---

Write tests for both cases above
Update README with demonstration of the above use cases

As a user, I would like to import my own custom assets

Type of Change

Summary

Greenwood needs to set a default asset directory for things such as additional CSS styles(not just global), images, and additional components. Some of these assets are needed for templates and others are needed from within markdown pages.

Details

I suggest the src/components directory should be the default components directory and perhaps an additional src/assets directory. These directories need to be copied to the .greenwood scratch directory before build. I would also suggest we copy over the src/templates folder as well otherwise no other page templates will work.

As a user I would like to configure my projects metadata

Type of Change

Summary

Basic site metadata will be needed in order to let application's configure the display of their site's information to crawlers and bots.

Details

Will want to support the creation of a greenwood.config.js file with these options.

{
  "title": "Greenwood Static Site Generator",
  "description": "A modern and performant static site generator supporting Web Components.",
  "url": "<project-website>"
  "type": "website"
}

These should be optional and not used if not provided
```
{
  "image": "path/to/logo"
}
```
Should dynamically update index.html
Nested pages should have a dynamically created url (nice to have, could be its own issue)
Write tests
Update README

[RFC] Public API / Userland Config

Type of Change

Summary

Greenwood will need to support the ability to let user's configure the greenwood build directly, like for being able to set additional paths, or project metadata.

This would also open up an easy path for #5

Details

As an initial test, greenwood should support

A greenwood.config.js file in the user's root / project workspace
It should allow the user to configure a different src/ directory (all other assumptions of pages, templates, etc will be the same.
Should have tests written for it
Should be documented in the README

# greenwood.config.js
const path = require('path');

module.export = {
  workspace: path.join(__dirname, 'www')
};

Note: Additional context configurations can be reviewed on a per item basis, but my feeling is all the context "state" should be handled as much as possible by greenwood.

As a user I would like default page template values based on filepath

Type of Change

Summary

Front matter for a give page may look something like

---
path: '/hello'
label: 'hello'
template: 'page'
---

### Hello World

This is an example page built by Greenwood.  Make your own in _src/pages_!

I think we could easily infer from defaults from the file name / path

Label
Path
Template (page is default)

Details

Allow Greenwood to provide defaults for the following, given a file path of
src/pages/blog/2019-03-31/index.md

Label: index
Path: /blog/2019-03-31/
Template: 'page'

add code coverage reporting and set thresholds

Type of Change

Summary

While we do have unit testing for this project, adding a coverage reporter would be a good way to ensure that we are covering (as much as possible) the critical code paths of the build.

Details

Could use something like nyc
https://stackoverflow.com/questions/16633246/code-coverage-with-mocha

A as user I would like appropriate API and Usage documentation

Type of Change

Summary

We'll want to document and comment a few things in this project as we get close towards wanting to share this

Details

Developer Docs

build
prod
serve

Usage

Project Structure
Creating a Page
commander commands

API Documentation

Page template
App template
Global CSS

Maybe in the wiki we can include architecture documentation about how the tasks / build works?

As a developer I should add Continuous Integration

Type of Change

Summary

Project should have continuous integration setup for it to make sure tests and linting is run

Details

Setup up CircleCI after #1 is completed.

As a developer I should have an app template provided by default

Type of Change

Summary

Related to #3

App template essentially generates the App Shell for the developers application, handles routing, and general performance concerns, and should essentially be managed / owned by Greenwood by default.

Page templates are being handled by #30

Details

Although a user can certainly make their own templates/app-template.js, as it's a complicated set of orchestrations (redux, routing, bundling, etc) and as such should be considered an "advanced" API.

So by default, and as a strong recommendation, Greenwood should assume its app-template.js will be the default one used and should be maintained / tested / documented as such.

HMR for local development

Type of Change

Summary

As opposed to watch / livereload, which refreshes the full browser on each local development change, enabling HRM (hot module replacement) can help speed up local development by only reloading the part of the page, that needs to change, not the whole application.

Details

For example, given a page with an <input> (for example):

Type something in the input element (like your name)
Change the CSS background of the page

expected: the page would change color, but the text in the input would remain

note: this might require needing to sync with a state management library like redux.

initial website scaffolding for development CI / CD

Type of Change

Summary

Set up a couple pages in a www folder to get thing started and a CI / CD pipeline to start deploying the website code to a webserver.

Details

Just enough to get the ball rolling.

Live-reload fails in development server when auto-generating labels for md files

Type of Change

Summary

Automatically generating labels requires a graph of the new labels to be sent to the markdown loader. When we live-reload, everything is rebuilt and previous generated labels are generated again with newly scaffolded components. The problem is the new graph is never sent to the webpack.config.common.js and then to the wc-markdown-loader.

Details

Possible solutions:

Reinitialize graph with parts of old graph(mainly the generated label name)
somehow return the new graph and reinit loader
worst case we have to write each graph to a file and read it within the markdown-loader, the path of which would be static and wouldn't need reinitializing.

If I do option one, it'll be tricky but doable. Check old graph if route exists, if so, use the same label. However the large limitations is If you add a single new md file, you will get the error:

(node:4044) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'label' of undefined
    at Object.loader (/media/skynet/DATA/workspace/evergreen/greenwood/node_modules/wc-markdown-loader/src/index.js:21:88)

because again, webpack.config.common.js will not reinitialize the graph. This one is a bit of a head scratcher for me at the moment. For this reason, option 2 + 3 would be better.

Tried option 2 a lot and not having any luck. It doesn't appear that webpack config object is reinitialized at all each build. Rather it uses the same config object from when you initially started it. IF there's a plugin to alter this somehow, I'd be very interested in it.

add tests for develop and serve commands

Type of Change

Summary

Although the develop tasks does start webpackDevServer, it would be good to see how much of it could actually be testable.

Details

If we can figure out a way to work around the dev server without influencing the actual running of greenwood too much, we should try, if at least for the basic generateCompilation step and that the command works as expected.

[RFC] Streaming vs File I/O Perfomance

Type of Change

Summary

Currently the building of the project is done by generating a SPA from the user's project directory, and then serializing that with a browser. The RFC here is to facilitate all that in memory and reduce the amount of filesystem I/O, and see if that can be fed directly to the serialize phase. (essentially cut out the scaffolding phase, somehow).

Details

One thought is to just use webpack-dev-server instead of local-web-server but in production "mode" so that we can drop the extra dependency and keep everything in memory.

Ideally this would help improve the build for larger projects.

an empty greenwood.config.js breaks the build (due to devServer?)

Type of Change

Summary

Having an empty greenwood.config.js results in a build error

module.exports = {};

$ yarn build
yarn run v1.12.3
$ node ./packages/cli/index.js build
-------------------------------------------------------
Welcome to Greenwood ♻️
-------------------------------------------------------
Reading project config
undefined
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

Details

Seems to be related to how devServer is being error checked perhaps (as part of #22 ), with no fallback handling?
https://github.com/ProjectEvergreen/greenwood/blob/master/packages/cli/lib/config.js#L29

running unit tests deletes root level greenwood.config.js

Type of Change

Summary

Running tests is cleaning root level files ...

Create an empty greenwood.config.js, e.g.

module.exports = {};

$ git status
On branch bug/issue-66-config-error-handling
Untracked files:
  (use "git add <file>..." to include in what will be committed)

	greenwood.config.js

nothing added to commit but untracked files present (use "git add" to track)
Owens-MBP-2:greenwood owenbuckley$ yarn test
yarn run v1.12.3
$ yarn clean && mocha --timeout 15000
$ rimraf ./.greenwood && rimraf ./public


  building greenwood with default context (no user workspace)
    ✓ should create a public directory
    public directory output
      ✓ should output a single index.html file (home page)
      ✓ should output one JS bundle file
      ✓ should create a default hello page directory
      default generated index page in public directory
        ✓ should output an index.html file within the root public directory
        ✓ should have the expected heading text within the index page in the public directory
        ✓ should have the expected paragraph text within the index page in the public directory
      default generated hello page directory
        ✓ should output an index.html file within the default hello page directory
        ✓ should have the expected heading text within the hello example page in the hello directory
        ✓ should have the expected paragraph text within the hello example page in the hello directory

  building greenwood with a user workspace w/custom nested pages directories
    ✓ should output one JS bundle
    ✓ should contain a nested blog page directory
    nested generated blog page directory
      ✓ should contain a nested blog page with an index html file
      ✓ should have the expected heading text within the blog page in the blog directory
      ✓ should have the expected paragraph text within the blog page in the blog directory
    a custom front-matter override page directory
      ✓ should contain a customfm folder with an index html file
      ✓ should have the expected heading text within the customfm page in the customfm directory
      ✓ should have the expected paragraph text within the customfm page in the customfm directory
      ✓ should have the expected blog-template's blog-content class

  building greenwood with user workspace that doesn't contain app template
    ✓ should create a public directory
    ✓ should contain a nested blog page directory
    public directory output
      ✓ should output a single index.html file (home page)
      ✓ should output one JS bundle
      ✓ should create a default hello page directory
      default generated hello page directory
        ✓ should output an index.html file within the default hello page directory
        ✓ should have the expected heading text within the hello example page in the hello directory
        ✓ should have the expected paragraph text within the hello example page in the hello directory
    nested generated blog page directory
      ✓ should contain a nested blog page with an index html file
      ✓ should have the expected heading text within the blog page in the blog directory
      ✓ should have the expected paragraph text within the blog page in the blog directory

  building greenwood with user workspace that doesn't contain page template
    ✓ should create a public directory
    ✓ should contain a nested blog page directory
    public directory output
      ✓ should output a single index.html file (home page)
      ✓ should output one JS bundle
      ✓ should create a default hello page directory
      default generated hello page directory
        ✓ should output an index.html file within the default hello page directory
        ✓ should have the expected heading text within the hello example page in the hello directory
        ✓ should have the expected paragraph text within the hello example page in the hello directory
    nested generated blog page directory
      ✓ should contain a nested blog page with an index html file
      ✓ should have the expected heading text within the blog page in the blog directory
      ✓ should have the expected paragraph text within the blog page in the blog directory

  building greenwood with user provided config file
    ✓ should output one JS bundle
    ✓ should contain a nested blog page directory
    nested generated blog page directory
      ✓ should contain a nested blog page with an index html file
      ✓ should have the expected heading text within the blog page in the blog directory
      ✓ should have the expected paragraph text within the blog page in the blog directory


  46 passing (42s)

✨  Done in 44.74s.
Owens-MBP-2:greenwood owenbuckley$ git status
On branch bug/issue-66-config-error-handling
nothing to commit, working tree clean

Note: git status is clean 🐰 🎩

Details

Exposed as part of #66

As a user I would like nested directory support for creating pages

Type of Change

Summary

Right now, Greenwood can only handle a pages directory that is one level deep (e.g. no subdirectories). This prevents users from being able to make more complex URLs, like

http://<domain.com/guides/readme

Details

The graph phase of the project should be able to recursively walk the pagesDir and graph all pages / routes.
An example of a structure that should work

src/
  pages/
    blog/
      20190326/
        index.md
    about.md