Please see new improved Stencil based components available at https://github.com/RocketCommunicationsInc/astro/blob/main/packages/web-components/readme.md and have your voice heard before release. The updated components are quite mature and we would encourage new projects to seriously consider using the updated Stencil components moving forward.
- If you find any bugs or issues, please file them here https://github.com/RocketCommunicationsInc/astro/issues
- If you have any questions or requests please ask them here https://github.com/RocketCommunicationsInc/astro/discussions
The Astro Web Component and CSS Library provides a starting point to begin developing Astro-compliant applications.
NOTE: The Astro Component Library is still new and tends to release breaking changes, but follows semver so you can control when you incorporate them. We typically follow a 6 month release schedule which includes two major release per year with breaking changes, and intermediate patch releases with bug fixes.
The directions below assume basic knowledge of NodeJS. Make sure you have installed both globally before continuing. An example can be seen on the Astro Storybook site
Create a new directory and change directory
mkdir astro
cd astro
Clone this repository
git clone https://github.com/RocketCommunicationsInc/astro-components.git
Install NPM modules for this project
npm i
Run the Storybook Server
npm run storybook
Visit the site locally, the Storybook CLI process will notify you of the correct URL, but you can typically view the site in your browser at http://localhost:9001/
To make use of this repository as a basis for your application you will need to implement your own build system. We recommend Open WC as a starting point.
For projects that won’t use the Web Component Library you only need the contents of the static directory.
Clone this repository
[email protected]:RocketCommunicationsInc/astro-components.git
Copy the contents of the static directory (css, fonts, icons, img, favicon.ico) to your project directory. Create a link to the CSS.
For development
<link rel="stylesheet" href="./css/astro.css" />For production
<link rel="stylesheet" href="./css/astro.min.css" />Follow the instructions for downloading and installing the CSS Library
Use npm to install the UI Library Elements required for your project. For example to intall an Astro Button
npm i -D @astrouxds/rux-button
The Astro Component Library is designed for use on modern browsers that support the W3C Custom Elements Standard. For backwards compatibility with Pre-Chromium Edge and Firefox versions prior to Firefox 63 you will need to use the web components polyfill
Follow the style defined in /.eslintrc, installing such tools as your IDE supports for revealing discrepencies before committing.
The folders in /src/components/* contain the Web Components, which are tested using matching Stories in /stories/*. The Story files create instances of the components with various properties exposed via Storybook Knobs. All component variations should be demonstrated using Knobs before publishing or updating to ensure that the properties work as intended. There are heavily commented templates for Stories (/stores/__rux-.stories.template.js) and Components (/src/components/__rux-template/) to enable maintainers to quickly scaffold new Components. These component folders are what are ultimately published on NPM under the AstroUXDS org.
Further information on Contributing to Astro Web Components
The Astro CSS library is used to style native HTML Elements and to set theme styles that are inherited throughout the application, even when developers do not use the Web Components themselves. The CSS is divided into partials in /src/css/*, which is concatenated into the /static/css/ files using PostCSS when the project builds using Gulp. See /gulpfile.js for more details.
Note: Changes to the Astro CSS should never be made directly to the /static/css/* files, as those are for distribution only.
Be sure to demonstrate any new or changed HTML elements using a Story. The Form Elements story (/stories/rux-form-elements.stories.js) shows how, even without a Web Component to mount, the functionality and variations can be displayed. If both Web Components and native HTML Elements can be used, such as in the case of Buttons (/stories/rux-button.stories.js), be sure to demonstrate both options.