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.
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 Rake:
bundle exec rake, you must run
bundle exec docs:preview.
Run a subset of tests by supplying a file glob to the test command:
TESTS="test/components/YOUR_COMPONENT_test.rb" bundle exec rake
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.
To run Storybook and the documentation site, run:
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 Storybook first, and then when it's in a good state, you can check it in your app.
git checkout -b my-branch-name
CHANGELOG.mdfor your change under the appropriate heading
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/.
We have both
production environments. To deploy Storybook to Heroku, run the following in
.deploy primer-view-components</branch> to <environment>
branch is passed,
main will be deployed.
script/releaseand follow the instructions.
script/publish. You may be prompted to log into your rubygem and npm account.
Publish releasebutton and you're good to go!