Create an evergreen web application with no build configuration, in the spirit of CRA and CLA
Clone or download
hutchgrant and thescientist13 Adding missing gitignore for npx install, closes #59 (#60)
* Adding missing gitignore for npx install, closes #59

* Rebasing with master

* Updating gitignore create

* Fixing lint errors

* Removing gitignore from blacklist and package.json
Latest commit 2f94ac4 Nov 21, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Adding customized package.json resolves #48, removing git clone (#51) Nov 16, 2018
.github Init bootstrapping (#1) Sep 23, 2018
docs generate latest pages Oct 27, 2018
src Updating style, resolve #22 (#42) Nov 18, 2018
tasks Adding missing gitignore for npx install, closes #59 (#60) Nov 22, 2018
.browserslistrc Init bootstrapping (#1) Sep 23, 2018
.editorconfig Init bootstrapping (#1) Sep 23, 2018
.eslintrc add ES2018 syntax support for CEA (#38) Oct 31, 2018
.gitattributes Init bootstrapping (#1) Sep 23, 2018
.gitignore Feature/issue 5 unit testing (#14) Oct 23, 2018
.npmignore setup for npm install (#11) Sep 25, 2018
README.md Bug/issue 57 npx install fail dev dependencies (#58) Nov 19, 2018
babel.config.js Init bootstrapping (#1) Sep 23, 2018
karma-test-shim.js Feature/issue 5 unit testing (#14) Oct 23, 2018
karma.conf.js Enhancement/issue 37 additional browser support karma (#39) Nov 6, 2018
lws.config.js Init bootstrapping (#1) Sep 23, 2018
package-lock.json Bug/issue 57 npx install fail dev dependencies (#58) Nov 19, 2018
package.json Adding missing gitignore for npx install, closes #59 (#60) Nov 22, 2018
postcss.config.js Init bootstrapping (#1) Sep 23, 2018
webpack.config.common.js Init bootstrapping (#1) Sep 23, 2018
webpack.config.develop.js Init bootstrapping (#1) Sep 23, 2018
webpack.config.prod.js enable performance budgets (#27) Oct 27, 2018
yarn.lock Bug/issue 57 npx install fail dev dependencies (#58) Nov 19, 2018

README.md

create-evergreen-app

GitHub release CircleCI branch GitHub issues GitHub issues GitHub license

Overview

A starter project for getting up and running with an evergreen web application development stack designed by, and for, today's modern web. Create Evergreen App

Project Goals

The goal of Project Evergreen is to march alongside the modern web and bring that to this repo so that both developers and users can benefit. Evergreen Web Applications aim to be performant, promote usage of modern web features, be accessible to a wide range of users, and be a productive experience for developers.

Acknowledgements

This project is made by possible with the much appreciated existence of tools like:

And of course, nods and kudos go out to the maintainers of Create React App (CRA) and Pascal Shlip (@thepassle) of Create Lit App for the inspiration.

Thank you, to all of you!

Under Development

This repo and Project Evergreen itself are still young and maturing rapidly. The Project Evergreen GitHub organization project tracker captures the high level goals and next steps, with plans to keep adding those lessons learned as features and improvements to this repo.

Immediate needs for this repo are:

  • Routing
  • Route based code spliting + Lazy Loading
  • Opt-in IE11 Support

🙏 Please feel free to contribute, we are always looking forward to meeting like minded developers to collaborate with!

Getting Started

Make sure you have a LTS version of Node.js installed and then follow these steps to get up and running:

# 1) Create new evergreen app
$ npx create-evergreen-app my-app

# 2) Change Directory
$ cd my-app

# 3) Start developing!
$ npm start

# or

$ yarn start

You can also clone the repo from GitHub

$ git clone https://github.com/ProjectEvergreen/create-evergreen-app.git my-app
$ cd my-app && npm install # or yarn install
$ npm start # or yarn start

📖 For more documentation and developer guides that cover topics like the build process, browser and device support, creating components, and more, please check out our wiki!

Usage

To start developing, you can simply go ahead and edit and add files as you need in src/.

ℹ️ Feel free to edit or delete any content / code related to Create Evergreen App (including README.md) to customize this repo to your own needs.

Development

Automated tasks have been made available as npm scripts that you can run from the command line using yarn or npm run:

  • develop - To start a development server with live reload and file watching
  • build - Generate a production build of the app for deployment
  • serve - Locally serve a production build
  • test - Run unit tests in TDD mode (prepend with NODE_ENV=production for "single run" usage)
  • start - alias to the develop task

e.g. to start developing, run

# yarn
$ yarn develop

or

# npm
$ npm run develop

Package Management

Your team may choose to use either npm or Yarn, just make sure to pick one and remove the other manager's lock file. Make sure to update the lock file whenever adding / removing a package.

Guides

These are some guides related to configuring different parts of this application to customize it for your needs.

Folder Structure

There is no right or wrong folder structure per se as with most decisions relating to technology, it's about finding the best tool for the job. Pick the conventions that fit your team / project best.

That said, CEA does come with with a lightly opinionated structure in the src/ directory as one of the main goals of a good folder structure should be to assist in the finding of files / code faster and being predicatable. Here is some info on the approach presented / suggested in this repo:

  • index.js - Main Entry point into the application (defined in webpack.config.common.js)
  • index.html - Defines the HTML "shell" of the application.
  • app/ - The top level "app" component, that will be used to bootstrap the application.
  • components/ - Essentially all the custom elements for an app will go here, encapsulating all reusable UI logic.
  • pages/ - Routable states and / or views that users will navigate to within an application.
  • services/ - Utilities for making (RESTful) API calls, convenience "wrappers" around browser APIs (Web Storage), etc. These generally don't interact with the DOM (that's what components are for).

Unit tests are recommended to be kept side by side with the component / class / etc. For integration and E2E tests, consider making a test/ directory alongside the src/ directory and put those tests there.

Setting Up (API) Proxies

In webpack.config.develop.js and lws.config.js are sections for setting up proxies for routing requests, say to an API running in your development envrionment. Edit the placeholders to match your particular needs.

CSS + Shadow DOM

// TODO

Performance

Performance is an important consideration for developing and maintaing any modern web application. Out of the box, this project uses webpack's default settings for performance budgets and will error when its thresholds are exceeded.

The goal of this project will be to support good code splitting and lazy loading strategies by default to allow apps to scale horizontally as more pages / features / dependencies get added.

To learn more about performance best practices for modern web application development, check out the wiki.

Unit Testing

For convenience, Create Evergreen App comes with the dependencies needed to run two browsers out of the box

  1. Chrome (headless w/Puppeteer)
  2. Firefox

Using Firefox

  1. Firefox (and other browsers) will likely need Custom Elements and Shadow DOM polyfilled. To add this polyfill in Karma, uncomment the lines in the files array in karma.conf.js related to ~@webcomponents.
  2. Add Firefox to the browsers array in karma.conf.js.
  • For information on adding more browsers, see the Karma docs.
  • For more information on testing in general, see our wiki!.

Chrome headless is enabled by default since it is the most portable between local and continuous integration environments.