ThinkNimble Vue Components Library

Welcome! This repository is where we host all of our reusable Vue components. It is also integrated with Storybook JS to provide a browsable gallery of components. This gallery is hosted at -> https://tn-vue-components.herokuapp.com/

Introduction

This is a "mono repo" that contains multiple components built as NPM packages. These packages are maintained and deployed to the @thinknimble NPM organization using a tool called Lerna. Each package/component also contains a corresponding stories file allowing the component and supporting documentation to be rendered in the Storybook library.

Installation

Follow these instructions to download and run the Storybook locally. This is useful if you are adding a new component to the library and are writing a related story to display in the gallery. You can run the storybook server locally with hot reloading and make sure everything looks good before opening a PR.

1. Clone this repository down locally
2. Run npm install, this should download everything needed to run Storybook. Additionally this will download Lerna, the tool we use to manage the multiple NPM packages contained in this repo.
3. Run npm bootstrap - This will run npm install within each package and download each components dependencies.
4. Once installation is finished, run npm run storybook. A webpage should open(normally at localhost:6006) containing the gallery! Any new stories you write in the /stories folder should show up here.

Contributing

Each component you contribute should be packaged up as an NPM package that can be downloaded into other projects. Follow along with the sections below to add a new component to the library:

Creating an NPM package Out of Your Component

1. Follow this guide to initialize the directory for your new component. Follow the instructions in the "Distribute a Vue Component as an NPM Package" section. This new directory should be placed in the /components folder.
2. Once all the necessary configuration is done for this directory, add the source files for your new component under the ComponentName/src/ directory.
3. You can use the testing instructions in the document above to make sure your component has been set up correctly to be published. Alternatively add it as a dependency to some other component's package.json and try to load it into the component.

Writing a Storybook Story for Your Component

A Storybook story is a file telling Storybook how to render your component for display in the web app. Each component must have an accompanying stories file contributed alongside it.

1. Inside the /stories directory, create a new file for your component called ComponentName.stories.mdx. Go ahead and create a folder if you'll need multiple files to write your story.
2. The ComponentName.stories.mdx file is written in MDX, a language format that is a mix between markdown and JSX. We utilize this to write the JavaScript to render our stories, as well as to write accompanying documentation around its use in markdown.
3. It is recommended to first take a look at Example.stories.mdx. We recommend copy/pasting this code into your own story file, then following along with the guide posted here to better understand how it works and adapt it to your own component.

Add your Component to Zeplin

The Storybook is connected to our Zeplin designs so that developers can see component documentation and a link to the component in Storybook when looking through designs. In order to ensure your component is showcased in Zeplin designs, follow these steps. Ignore this if you are not connecting your component to Zeplin.

1. Open up .zeplin/components.json in this repo.
2. Within "components", just add a new object for your component, it should look like this:

"components": {
  ...,
  {
    "path": "components/new-components/src/components/NewComponent.vue",
    "zeplinNames": [
      "Components / NewComponent*"
    ]
  }
}

That should be all you need to do! When the component is accepted and merged it will be auto-connected to Zeplin.

Updating Your Component

When you go to modify or extend an existing component, please be sure to increment the version number in package.json appropriately based on whether it is a patch, minor, or major version update. This will ensure that the package is properly updated in NPM.

It is recommended to simply increment the version number and leave the publishing to Lerna. If you do publish your component yourself, again just update the version number in package.json to reflect the version published to NPM. Lerna will skip updating packages where the version number in the package has already been published.

General Contribution Guidelines

1. Every component must be bundled as a distributable NPM package in the /components directory, and must include a corresponding Stories file in the /stories directory.
2. Please try to submit one new PR for each new component you are adding.
3. The accompanying Storybook story is required for the component to render in the gallery. See the resources above and the documented components in this repository for assistance.
4. Please comment your source files appropriately and include information on who contributed the component for maintenance purposes.

Deployment

We utilize Lerna to execute commands across all NPM packages inside this repo. It is useful for bootstrapping the repository, running tests/linting across all packages, and for deployment!

To Deploy

To deploy any changed packages, pull down the master branch and run npm run publish. This will:

1. Detect all packages where the source code has changed and the current version number in package.json has not already been published to NPM.
2. Give a confirmation prompt for the updates to be made.
3. Deploy all changed packages to NPM.

Contact

Please contact [email protected] or [email protected] with any questions or concerns.