Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
If you have any substantial changes that you would like to make, please open an issue first to discuss them with us.
Contributions to this project are released to the public under the project's open source license.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
Use the provided generator to create a component:
bundle exec thor component_generator my_component_name
To declare a dependency on an
npm package, pass
js to the generator:
bundle exec thor component_generator my_component_name --js=some-npm-package-name
Components and slots should restrict which HTML tags they will render. For example, an
Image component should never be rendered as an
Consider which HTML tags make sense. Components typically fall under one of the following patterns:
1) Fixed tag that cannot be updated by the consumer:
system_arguments[:tag] = :h1
2) Allowed list of tags that are set with the
tag: argument using the
system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, DEFAULT_TAG)
Before running the whole test suite with:
script/test, you must run
bundle exec rake docs:preview.
Run a subset of tests by supplying arguments to
script/test FILEruns all tests in the file.
script/test FILE:LINEruns test in specific line of the file.
script/test 'GLOB'runs all tests for matching glob.
GLOBin single quotes
By default, the system tests run in a headless Chrome browser. Prefix the test command with
HEADLESS=false to run the system tests in a normal browser.
Documentation is written as YARD comments directly in the source code, compiled into Markdown via
bundle exec rake docs:build and served by Doctocat.
bundle exec rake docs:build
/rails/view_components/in your browser
bundle exec rake docs:previewand refresh the page.
To run the documentation site and the demo app, run:
If you are running into issues or not seeing your updates, a few things you can try:
overmind.sockfile and run
node_modulesdirectory and re-run
bundle exec rake docs:build
bundle exec rake docs:preview
Note: Overmind is required to run script/dev.
gem "primer_view_components", path: "path_to_the_gem" # e.g. path: "~/primer/view_components"
bundle install to update references. You'll now be able to see changes from the gem without having to build it.
Remember that restarting the Rails server is necessary to see changes, as the gem is loaded at boot time.
To minimize the number of restarts, we recommend checking the component in Lookbook first, and then when it's in a good state, you can check it in your app.
git checkout -b my-branch-name
Here are a few things you can do that will increase the likelihood of your pull request being accepted:
componentslist in Rakefile in the
docs:buildtask, so that Markdown documentation is generated for them within docs/content/components/.
The Rails lookbook is currently deployed via GitHub Actions using this workflow. Deployments happen automatically on every merge to the
main branch. The lookbook runs in a Kubernetes cluster hosted within our team's Azure subscription. Please contact a member of the team for access.
To publish a release, you must have an account on rubygems and npmjs. Additionally, you must have been added as a maintainer to the project. Please verify that you have 2FA enabled on both accounts.
script/publish. This will build and publish the packages. You may be prompted to log into your rubygem and npm account.