terra-toolkit
Version:
Utilities to help when developing terra modules.
93 lines (59 loc) • 5.48 kB
Markdown
<!-- Logo -->
<p align="center">
<img height="128" width="128" src="https://github.com/cerner/terra-toolkit-boneyard/raw/main/terra.png">
</p>
<!-- Name -->
<h1 align="center">
Terra Toolkit
</h1>
[](https://www.npmjs.org/package/terra-toolkit)
[](https://github.com/cerner/terra-toolkit-boneyard/blob/main/LICENSE)
[](https://travis-ci.com/cerner/terra-toolkit-boneyard)
[](https://david-dm.org/cerner/terra-toolkit-boneyard)
[](https://david-dm.org/cerner/terra-toolkit-boneyard?type=dev)
Terra Toolkit is a utility module used to facilitate independent development of Terra projects. This toolkit provides build scripts, configurations, and Webdriver Services needed to serve assets, compile webpack, and run webdriver.io tests to streamline development of npm packages.
[terra-core][@terra-core], [terra-clinical][@terra-clinical], and [terra-framework][@terra-framework] are a few examples repositories which are utilizing the utilities offered in this package.
[terra-dev-site][@terra-dev-site] is a node module that extends the configurations offered by toolkit.
- [Getting Started](#getting-started)
- [Serve Options](#serve-options)
- [Webdriver.io Utility](#webdriverio-utility)
- [Webpack Configuration](#webpack-configuration)
- [Versioning](#versioning)
- [Contributing](#contributing)
- [LICENSE](#license)
## Getting Started
- Install toolkit and its peer dependencies as dev-dependencies with [npm](https://www.npmjs.com):
```bash
> npm install --save-dev terra-toolkit webpack webpack-cli webpack-dev-server @babel/cli @babel/core
```
To use Terra Toolkit for local webdriver testing, you must install docker on your machine.
- Install Docker version 17.09.0 or higher. Installation instructions can be found at https://docs.docker.com/install/.
## Theme Aggregation
Terra Toolkit provides a built-in mechanism for aggregating themes.
See the [Theme Aggregation](https://github.com/cerner/terra-toolkit-boneyard/blob/main/scripts/aggregate-themes/README.md) to get started.
## Serve Options
Terra Toolkit offers two ways to serve your client side application, `serve` and `serve-static`. Serve provides a hot-reloading, development only option via [webpack-dev-server](https://github.com/webpack/webpack-dev-server), while serve-static is a non-hot-reloading [express](https://expressjs.com/) server. Serve-static supports IE10 and is used in webdriver testing.
See the [Serve Guide](https://github.com/cerner/terra-toolkit-boneyard/blob/main/scripts/serve/Serve.md) to get started.
## Webdriver.io Utility
[Webdriver.io](http://v4.webdriver.io/) is a framework for writing webdriver powered tests to validate functionality in browsers. The Webdriver.io framework provides services for setting up a selenium server, starting webpack and static servers, running accessibility and visual regression testing, and more.
See the [Webdriver.io Utility Developer's Guide](https://github.com/cerner/terra-toolkit-boneyard/blob/main/docs/Wdio_Utility.md) to get started.
## Webpack Configuration
[Webpack](https://webpack.js.org/) is a module bundler used to compile modules with dependencies and generate static assets. Webpack is a very powerful tool that is highly configurable and Terra components rely on specific polyfills, webpack loaders and plugins to render correctly. Terra provides a [default webpack configuration](https://github.com/cerner/terra-toolkit-boneyard/blob/main/config/webpack/webpack.config.js) which we recommend you extend to meet your needs. By using this default configuration, we will manage webpack dependencies and set up translation aggregation.
See the [Webpack Configuration Guide](https://github.com/cerner/terra-toolkit-boneyard/blob/main/docs/Webpack.md) to get started.
## Versioning
Terra-toolkit is considered to be stable and will follow [SemVer](http://semver.org/) for versioning.
1. MAJOR versions represent breaking changes
2. MINOR versions represent added functionality in a backwards-compatible manner
3. PATCH versions represent backwards-compatible bug fixes
Consult the component CHANGELOGs, related issues, and PRs for more information.
## Contributing
Please read through our [contributing guidelines](CONTRIBUTING.md). Included are directions for issue reporting and pull requests.
## LICENSE
Copyright 2017 - 2020 Cerner Innovation, Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
[@terra-core]: https://github.com/cerner/terra-core
[@terra-clinical]: https://github.com/cerner/terra-clinical
[@terra-framework]: https://github.com/cerner/terra-framework
[@terra-dev-site]: https://github.com/cerner/terra-dev-site