Elements is a UI library built by Foxy. If you see someone on the team mention "Foxy Elements", "Elements", "foxy-elements", "@foxy.io/elements", "elements package" or "elements repo", they're most likely referring to this project. We hope this document makes the process for contributing clear and answers some questions that you may have.
Foxy has adopted the Contributor Covenant as its Code of Conduct, and we expect project participants to adhere to it. Please read the full text so that you can understand what actions will and will not be tolerated.
All work on Elements happens directly on GitHub. Both team members and external contributors send pull requests which go through the same review process. In the same time, Elements is not a community-driven project, so we will always prioritize our own needs and the needs of our customers when it comes to feature requests.
Elements follow semantic versioning. We release patch versions for bug fixes, minor versions for backwards-compatible features, and major versions for any breaking changes. Significant changes may also appear in a pre-release before they become generally available. Release notes are available on this page.
We have two release branches: main and beta. Whenever someone commits changes to them, GitHub Workflows create a release and publish it to npm almost immediately. Only stable, tested and reviewed code is allowed on main. Unstable, untested or not yet reviewed code may appear on beta. If your code breaks the build or causes serious runtime errors, please keep it in a separate branch until it's ready.
We are using GitHub Issues for our public bugs. We keep a close eye on this and try to make it clear when we have an internal fix in progress. Before filing a new task, try to make sure your problem doesn’t already exist. If you've come across a security issue in this project, please consider letting us know before opening a public issue.
You can find all the ways you can contact us on this page.
If you intend to change the public API, or make any non-trivial changes to the implementation, we recommend filing an issue. This lets us reach an agreement on your proposal before you put significant effort into it.
If you’re only fixing a bug, it’s fine to submit a pull request right away but we still recommend to file an issue detailing what you’re fixing. This is helpful in case we don’t accept that specific fix but want to keep track of the issue.
Working on your first pull request? You can learn how from this free video series.
If you decide to fix an issue, please be sure to check the comment thread and the list of assignees in case somebody is already working on a fix. If nobody is working on it at the moment, please leave a comment stating that you intend to work on it so other people don’t accidentally duplicate your effort.
The team is monitoring for pull requests. We will review your pull request and either merge it, request changes to it, or close it with an explanation. We might also decide to keep it open to make sure your changes align with the internal roadmap for other Foxy products. In any case, we’ll do our best to provide updates and feedback throughout the process.
Before submitting a pull request, please make sure the following is done:
- If you don't have write access, fork the repository.
- Create your branch from
main. - Run
npm installin the repository root. - If you’ve fixed a bug or added code that should be tested, add tests.
- If you’ve changed the public interface, run
npm run wcaand commit changes incustom-elements.json. - Ensure the test suite passes (
npm test). Tip:./node_modules/.bin/wtr TestPattern --watchis helpful in development. - Run
npm run prepackandnpm run build:storybookto test that your code doesn't break the build. - Format your code with prettier (
npm run format). Make sure your code lints. - If you haven’t already, complete the CLA.
In order to accept your pull request, we need you to submit a CLA. You only need to do this once, and a bot will send you a reminder in case you forget. Complete your CLA here.
Each UI component in this library is a custom element based on LitElement. Our design system is built on Vaadin 14 with a set of custom TailwindCSS utilities providing shortcuts for Lumo colors, fonts, sizing and spacing. Translations are handled through i18next. We use Web Dev Server with Storybook for development, Web Test Runner for testing, Rollup for CDN builds and a custom TypeScript compiler for npm releases. Code style is enforced with Prettier and ESLint, commit style is maintained with Commitizen. We develop using Git, Node v14+ and npm v7+.
After cloning Elements, run npm install to fetch the dependencies. Then, you can run several commands:
npm run wcaregeneratescustom-elements.jsonwhere all elements are documented.npm run storybooklaunches Storybook with Web Dev Server.npm run storybook:buildbuilds Storybook with Rollup.npm run lintchecks the code style with both ESLint and Prettier.npm run lint:eslintchecks the code style with ESLint only.npm run lint:prettierchecks the code style with Prettier only.npm run formatfixes code style issues with both ESLint and Prettier.npm run format:eslintfixes code style issues with ESLint only.npm run format:prettierfixes code style issues with Prettier only.npm run testruns the complete test suite.npm run test:watchruns an interactive test watcher.npm run test:playwrightruns tests in major browsers with Playwright (experimental).npm run prepackcreates adistfolder for npm distribution.
We use an automatic code formatter called Prettier. Run npm run format:prettier after making any changes to the code. Then, our linter will catch most issues that may exist in your code. You can check the status of your code styling by running npm run lint:prettier.
By contributing to Elements, you agree that your contributions will be licensed under its MIT license.