@hackthenorth/north NPM

North

North is Hack the North's frontend component library, built for use in React.

Check it out

Usage

Installation

First, install the package in your project:

$ npm install --save @hackthenorth/north

Defining a theme

North components derive their styling from a theme definition file.

When creating a theme for North, you can provide the following in your theme definition:

globalStyles: a css object that defines styles to be applied globally
globalConstants: an object containing constants that you want to be able to access when defining styled components
deviceBreakpoints: an object containing maximum width breakpoints for different device names
modifiers: each North component can have two properties defined in the theme definition:
- sharedStyles: similar to globalStyles, this defines styles shared by all instances of this specific North component
- mods: each key you specify in this property will be a modifier name that can be specified when using a North component to apply the corresponding style values defined in modifiers. A component can use multiple modifiers using any format accepted by the classnames library. Example usage:
```
  <Button mods="error"/>
  <Button mods=["error", "secondary"]>
  <Button mods={error: SOME_CONDITIONAL, secondary: ANOTHER_CONDITIONAL}>
```

An example of a theme definition can be found in src/themes/storybook.ts, and more detailed schemas can be found through the TypeScript interface definitions in the source code.

Providing theme to components

After your theme has been defined, provide it to North by wrapping your application with a North provider component.

// yourApp.js
import { North } from "@hackthenorth/north"; // import the provider
import YOUR_THEME_DEFINITION from "path/to/your/theme-def/file"; // your theme definition file

const App = () => (
  <North themeDefinition={YOUR_THEME_DEFINITION}>
    // rest of your app here...
  </North>
);

Using components

To use a themed North component:

import { Card } from "@hackthenorth/north"; // import the component

// ...your component...
return <Card mods="YOUR_MODIFIER_NAME" />;
// ...your component...

The modifier name should be defined in your theme definition under the modifiers property of the component you're using.

Development

Setup

First, clone the repo:

$ git clone https://github.com/hackathon/north.git
$ cd north

Then install dependencies and get it running:

$ npm install
$ npm start

Navigate to localhost:9001 in your browser. This will load the Storybook documentation for North, where you can see every component in the North component library.

Adding a new component

Here's a handy dandy checklist to cover when you're adding a new component:

Make sure the component has its ref forwarded
Make sure both the unstyled and themed versions of the component have displayNames set
Add tests (if necessary) in a .test.tsx file
Add stories in a .stories.tsx file
Add the component to the themeFromDefinition function here (in alphabetical order)
Export the component with the rest of North here (in alphabetical order)
Add typings for the component and its props to both the ThemeDefinition and Theme interfaces here (in alphabetical order)

Releasing a new version

When changes are ready to be released, do the following:

Make a pull request from master into release
Prefix your pull request title with one of [major]|[minor]|[patch] based on the changes and (very roughly) according to semantic versioning
Merge once all CI/checks pass

The hackthenorth-platform bot will automatically tag the release based on the previous version and your prefix before building and publishing the new version of the package to npm.

Tech stack

React
styled-components
Jest
Storybook
Rollup
Buildkite
TypeScript
Github Pages

Components are built with React, and written in TypeScript. Tests are written in Jest, and test functionality as well as snapshot comparisons. The website is just an instance of Storybook, deployed to Github Pages by Buildkite every time we publish a new version. Rollup is used to create the published package.

We use styled-components to apply styles and for the theming ability that it provides.