This is a monorepo containing the elements required for building experiences following the EnergySage Design System, or es-ds for short.
This repository es-ds
is public and the contents are licensed under the
MIT
For that reason discussion and documentation specific to EnergySage should probably be kept within private org channels.
For EnergySage specific resources & channels see the Quick Links section of the Design System confluence page
Starting in version 3.0, the EnergySage Design System is composed of 2 core npm packages:
graph TB
subgraph es-ds
subgraph "@energysage"
A["@energysage/es-bs-base"]
C["@energysage/es-ds-components"]
end
D[es-ds-docs]
C-->D
end
Y(nuxt3)
Z(primevue) --> C
Y-->D
es-bs-base
- es-bs-base started as a fork of Bootstrap 4.
- This package overrides the
_variables.scss
file in Bootstrap to the defaults required by the EnergySage design system. - There are additional variables and colors that diverge and extend from the core Bootstrap framework.
- The SASS has also been refactored to use the modular system and dart-sass compiler.
- Prior to v3.0,
es-bs-base
worked with thees-vue-base
package, which is based on bootstrap-vue. As such, there are still some legacy Bootstrap Vue styles present ines-bs-base
. Those are deprecated and will be removed in a future version.
es-ds-components
- es-ds-components contains Vue 3 components for use in Nuxt 3 projects. It is primarily based on PrimeVue, with some customizations specific to EnergySage.
es-ds-docs
- This is the design system documentation site powered by Nuxt 3.
- It also serves a reference for
how to integrate
es-ds
packages into a Nuxt 3 project.
Prior to version 3.0, the EnergySage Design System was composed of 2 core npm packages:
graph TB
subgraph es-ds
subgraph "@energysage"
A["@energysage/es-bs-base"]
C["@energysage/es-vue-base"]
end
D[es-design-system]
C-->D
end
Y(nuxt2)
Z(bootstrap-vue) --> C
Y-->D
es-vue-base
- es-vue-base contains vue components for use in nuxt projects. It has a dependency of bootstrap-vue as components extends or are composed of bootstrap components.
es-bs-base
is a sibling dependencies and should provide the baseline CSS styling to vue rendered components.
es-design-system
- This is our v2.x design-system documentation site, and reference integration for
the
es-ds
packages.
clone git@github.com:EnergySage/es-ds.git
When publishing changes you will commit to the origin branch of the es-ds repo. So your git set-up should look like this:
$ git remote -v
origin git@github.com:EnergySage/es-ds.git (fetch)
origin git@github.com:EnergySage/es-ds.git (push)
v3.0 and later
make install
- installs all packages from npm
v2.x and earlier
make legacy-install
- installs all packages from npmmake legacy-update-peer-deps
- installs necessary peer deps fores-vue-base
used ines-design-system
make legacy-build-scss-pkg
- buildes-bs-base/dist
locally; we do this first sincees-vue-base
imports it@import '~@energysage/es-bs-base/scss/includes'
make legacy-symlink
- symlink or bootstrapes-bs-base/dist
make legacy-build-vue-pkg
- buildes-vue-base/dist
locallymake legacy-symlink
- symlink or bootstrapes-bs-base/dist
andes-vue-base/dist
for use ines-design-system
make dev
This command will:
- Locally link your
es-bs-base
andes-ds-components
folders to thees-ds-docs
Nuxt app - Start the
es-ds-docs
local dev server
You can then make changes as desired in either upstream package folder and the local dev server should immediately reflect those changes.
make unlink
This command will:
- Undo the local linking set up by the above command
- Reinstall the public NPM versions of the
es-bs-base
andes-ds-components
packages
This enables you to run the es-ds-docs
server with the state of code that is publicly available on NPM.
cd es-ds-docs
npm run dev
These commands will:
- Run the
es-ds-docs
local dev server without locally linking to thees-bs-base
andes-ds-components
packages folders - Whichever versions of the two upstream packages are installed (or already locally linked) will be used
To develop with hot reloading for all packages you'll want to run make legacy-dev
in
the es-ds
directory. This will build and package es-bs-base
and
es-vue-base
and symlink them to es-design-system
for use in the nuxt app. It
will then start a dev instance for es-design-system
that will be available at
http://localhost:8500
.
Hot reloading will take longer than a typical nuxt app, as it will need to rebuild the packages and re-link them. This is expected.
Faster reloads hack
In a terminal run:
find es-vue-base/src/ | entr -s 'npm --prefix es-vue-base run build'
(You may need to run brew install entr
first)
In another terminal run:
(cd es-design-system && FAST_LOCAL=true npm run dev)
This will result in much faster reloads that skip rebuilding all of es-bs-base
as well as skipping server-side rendering. But note this will also throw an
error in webpack-dev server until es-vue-base
finishes compiling, then it
should recover.
You must also ensure things work server-side before committing your changes.
Once we upgrade to Lerna 6, this should all be much faster & smoother via native Workspace watching
When adding vue components to es-vue-base, it is expected that you also write unit-tests.
At a minimum it's recommended you create a snapshot test to catch any potential regressions in rendered output. Depending on complexity further tests may be required.
Tests can be run via make test
, but this will run tests for all packages in
the repo. For faster feedback, you can cd es-vue-base
and run npm run test
to only run tests for the es-vue-base package.
Once tests are passing, you'll need to rebuild the es-vue-base package. This
can be done via npm run build
.
Next you'll want to move back to the root of the monorepo, and run make symlink
. This will ensure the new package is sym-linked to the other projects
in the monorepo.
Once your changes have been made, you'll want to ensure they're documented
somewhere in es-design-system
. If the change is a new component, it's expected
you'll create a new page to display the component.
Note This step also functions as a form of integration testing as it will validate the component will import and render on a nuxt page.
In your PR, make sure to include a section in the changelog documenting your change. Following keep a changelog conventions this will look similar to the following:
## [Unreleased]
### Added
- Thing one
### Changed
- Thing two
This will make it easier to ensure all changes merged into main
are captured
in the changelog when publishing a new release.
For simplicity of deployment, versioning of packages are fixed and updated together.
Assuming changes are approved, the process of publishing a new version is...
0. Ensure your local environment is
setup and you are on
the main
branch
- Make sure the package.json versions in
es-bs-base
andes-ds-components
is updated to a new version that hasn't been published before on NPM. npm login
- Logs you into the npm.js registry. You'll need access to oures-ds
package there in order for things to work.make install && make symlink
- Install and symlink dependencies locallymake build
- Build all packages to*/dist
folders locallymake lint && make test
- Run tests and linting to ensure they passmake publish
- Publish updated packages to npmjs.com- Update CHANGELOG.md with our newly published changes
make update-docs-deps
- Install the new published versions locallygit commit -m "docs: :memo: add version X.X.X to the changelog" && git push
- Commit and push the changelog andpackage-lock.json
updates
Assuming changes are approved, the process of publishing a new version is...
- Ensure your local environment is
setup and you are on
the
main
branch npm login
- Logs you into the npm.js registry. You'll need access to oures-ds
package there in order for things to work.make legacy-install && make legacy-symlink
- Install the new published versions locally and symlink themmake legacy-build
- Build all packages to*/dist
folders locallymake legacy-lint && make legacy-test
- Run tests and linting to ensure they passmake legacy-publish
- Publish updated packages to npmjs.com- Update CHANGELOG.md with our newly published changes
make legacy-install && make legacy-symlink
- Install the new published versions locally and symlink themgit commit -m "docs: :memo: add version X.X.X to the changelog" && git push
- Commit and push the changelog andpackage-lock.json
updates- For updating the design-system website see Deploy Design System
Running make legacy-publish
will trigger the following prompt:
lerna info Looking for changed packages since v0.1.9
? Select a new version (currently 0.1.9)
❯ Patch (0.1.10)
Minor (0.2.0)
Major (1.0.0)
Prepatch (0.1.10-alpha.0)
Preminor (0.2.0-alpha.0)
Premajor (1.0.0-alpha.0)
Custom Prerelease
Custom Version
You'll note the lerna script will walk you through versioning, then push your changes, and tag the release in git.
This project follows semantic versioning. Please make sure your change in version reflects the semantics defined via semver. At a high level the guidelines are:
- MAJOR version changes introduce incompatible API changes. API changes could
mean:
- removal of core-components used in other verticals
- changing "props" of core-components causing breaking changes in other verticals
- MINOR version changes add functionality in a backwards compatible manner.
This could mean:
- changing the hex value represented by the variable
$white
ines-bs-base
- adding an additional "prop" to a core-component, but otherwise not chancing the default behavior
- changing the hex value represented by the variable
- PATCH version changes are backwards compatible bug-fixes and should have no impact on functionality aside from fixing a bug