@sproutsocial/racine

    8.6.2 • Public • Published

    Racine

    React components for Sprout Social's user interfaces

    📖 View the documentation for Racine in Sprout's design system, Seeds ▸

    🆕 Learn about what's changing in the CHANGELOG.md file ▸

    🚧 Check out the project board to see what's in-flight and upcoming ▸


    Installation

    Install Racine using npm or yarn:

    $ yarn add @sproutsocial/racine react styled-components
    # or
    $ npm install @sproutsocial/racine react styled-components

    You may also require specific peer dependencies when starting a new project or sandbox environment:

    @sproutsocial/seeds-border
    @sproutsocial/seeds-color
    @sproutsocial/seeds-depth
    @sproutsocial/seeds-motion
    @sproutsocial/seeds-networkcolor
    @sproutsocial/seeds-space
    @sproutsocial/seeds-typography
    moment
    prop-types
    react
    react-dates
    styled-components

    Then, wrap your app's React root in Racine's ThemeProvider component:

    import { ThemeProvider } from '@sproutsocial/racine'
    
    const App = props => (
      <ThemeProvider>
        <div>your app here</div>
      </ThemeProvider>
    )

    Documentation

    Racine is documented in Sprout's design system, Seeds ▸

    Racine uses Storybook as a local development environment, and for running tests against components. Every component has a .stories.js file where developers can write "stories" to test components in isolation. Running yarn start will open the Racine Storybook in your browser so that you can see changes live as you make them. You can read more about writing stories on the Storybook website.

    Local development

    Racine uses Storybook for local development. Here's how to get started:

    1. Clone this repo: git clone https://github.com/sproutsocial/racine
    2. Install dependencies: yarn
    3. Run the dev app: yarn start
    💡 If you need to test local Racine changes in another project, click here to learn how.

    Test any local package in another project by utilizing yarn link. Below is an example workflow to link Racine to web-app-core.

    1. Navigate to your local copy of Racine in a terminal window
    $ cd ~/YourCodeFolder/racine
    $ yarn link # only needs to be run once
    $ yarn start

    Note: This build task packages all Racine components into the bundle, not just the specific components you are adding or modifying. After yarn link succeeds and Racine is globally linked, you shouldn't have to run link again.

    1. Navigate to the folder you wish to use Racine components in your terminal (such as web-app-core) and complete the link
    $ cd ~/YourCodeFolder/web-app-core
    $ yarn link "@sproutsocial/racine"
    $ yarn start
    1. You can now use any components from your local instance of Racine in your project. See below for an example usage
    /* ~/YourCodeFolder/web-app-core/YourFile.js */
    import {Icon} from '@sproutsocial/racine';
    // ...
    <Icon name='compose' />
    1. When you are done, be sure to unlink Racine so you are using the app's version of the package
    $ yarn unlink "@sproutsocial/racine"
    $ yarn
    

    Contributing

    Contributions to Racine are welcomed and encouraged from every member of the team. Whether you're adding a new component or simply fixing a bug, every improvement to the library is future leverage for our peers, our product, and our customers.

    🔍 Step 1: Find a way to contribute

    There are a few ways to get involved:

    🗺 Step 2: Find your way around

    Racine's file structure is set up like this:

    • codemods - For major updates to Racine that have breaking changes, codemods are included for automatically handling component API updates.
    • src
      • ComponentName - Every component in Racine has a folder within the src directory.
        • index.js - This file should export the component as its default export.
        • index.stories.js - Storybook stories can be written here.
        • index.test.js - All component tests live inside this file.
        • styles.js - Any style-specific components live here.
      • utils - This directory includes a set of common utilities and helpers that we use throughout Racine.

    And you can interact with Racine via the command line with these commands:

    • yarn new - This command will prompt you for the name of your component, and then generate all of the boilerplate you need to create the component.
    • yarn start - This will watch the Racine package for changes, and also run Storybook locally so that you can see your changes as you go.
    • yarn change - This command will generate a changeset file that is used to document changes to the Racine package. If you are making a PR to Racine that should result in a version bump to the package, you will need to run this command to add a changeset. You can learn more about this command in step 3.
    • yarn build - Generate production builds for the Racine package.
    • yarn test - Run Racine's test suite. Note: yarn start must be run before yarn test to build generated files and directories
    • yarn clean - Delete all generated files and directories.
    • yarn release - This will trigger the release process for creating a new version of the Racine package on npm. Only Racine administrators can perform the release process.

    Step 3: Make your changes

    Racine uses a tool called changesets to automatically pick new version numbers and update the changelog whenever we publish a new version of the package.

    Run yarn change to generate a changeset that will be used to derive the next version number for Racine from your changes.

    We use semantic versioning for the Racine package, which allows users to understand the scope of a package's changes based on the version number, which is in the format major.minor.patch.

    When running this command, you will be asked to select whether your change is a patch, minor, or major change.

    • patch changes are for bug fixes, and they bump the last digit in the version number (x.x.0)
    • minor changes are for new features or improvements, and they bump the middle digit in the version number (x.0.x)
    • major changes are breaking changes, and they bump the first digit (0.x.x). These types of changes are rare and should be coordinated in advance with the Design Systems team.

    The changeset CLI will also ask you to input a message detailing your changes. The completion of the command will generate a new changeset markdown file. You are more than welcome to edit this file after it has been generated, so don't get hung up on trying to write the perfect text from the command line. Aim to make the text of the changeset file(s) as descriptive and informative as possible, as they will be used to build a changelog file when the new version is released.

    You can add as many changesets to a PR as you would like. If your PR makes several distinct changes to Racine, you should create a changeset detailing each one individually.

    🗣 Step 4: Create a pull request

    Once you're ready to submit your changes for review, open a PR to this repository. A few things will happen:

    • The Racine maintainers will be tagged to review your code. Feel free to tag any specific individuals who you think should take a look.
    • Racine's test suite will be ran on CI, and the status will be reported on the PR. You can run yarn test to run these tests locally. If there are any issues, they will need to be resolved before the PR can be merged.
    • Netlify will create a preview deploy of Racine's Storybook so that you can see your changes and share them with others.

    Once your tests are passing and you have at least one approving review, feel free to merge your changes into Racine!

    ☁️ Step 5: Publish your changes to npm

    As PRs get merged into Racine, changsets will keep a running PR open called Version Packages. This PR will detail all of the changes that have been made to the package since the last publish. Anyone can release a new version of Racine by merging this PR.

    When the PR is merged, GitHub will kick off a publish of the new version. There will be a notification in #eng-design-systems in Slack when the new version is available.

    Step 6: Document your changes

    Racine components are documented in Seeds, Sprout's design system. You can open a PR to the Seeds repository to add or edit component documentation. Reach out to the Design Systems team for help getting started.

    Keywords

    none

    Install

    npm i @sproutsocial/racine

    DownloadsWeekly Downloads

    1,149

    Version

    8.6.2

    License

    MIT

    Unpacked Size

    2.87 MB

    Total Files

    909

    Last publish

    Collaborators

    • mtrums
    • sprout-publish
    • joyellewoodson
    • mosleywm
    • soung3
    • tmcwilliam
    • jritterbush
    • benthemonkey
    • conwaydev
    • chrisege
    • dgarofalo
    • zpaul
    • gordonkristan
    • dansnetwork
    • balanceiskey
    • bambu-npm
    • jryding
    • notthefakecory
    • shreya317
    • stanton47
    • timrwhi
    • bfoehring
    • kbrtrm
    • sprout-npm
    • mchlltt
    • margie
    • hjylewis
    • xmwl
    • ianduvall
    • bensprout
    • madelynnelson
    • ryansprout