# sewing_kit

Zero configuration, high performance front end development at organization scale.

This document focuses on Rails integration.  For details of `sewing-kit`'s configuration and usage, see the [sewing-kit documentation](https://github.com/Shopify/sewing-kit#sewing-kit).

## Quick Start
Create a Rails project using `dev init` then:

### Install Sewing Kits
```sh
# Add Ruby/Node dependencies
bundle add sewing_kit
yarn add --dev @shopify/sewing-kit
yarn add --dev react-hot-loader@3.0.0-beta.7

# Optional - add Polaris
yarn add @shopify/polaris react react-dom

yarn
dev up
```

### Add JavaScript
sewing_kit looks for JavaScript in `app/ui/index.js`.  The code in `index.js` (and any imported JS/CSS) will be built into a `main` bundle.

### Link to JS/CSS with `erb` Helpers
The `main` bundle is imported into `erb` files using Rails helpers:

```erb
<%= sewing_kit_link_tag *sewing_kit_assets('main', extension: 'css') %>
<%= sewing_kit_script_tag *sewing_kit_assets('main') %>
```

**Note:** CSS `<link>` tags appear only in production; in development, CSS is embedded within the `main.js` bundle.

## Minimal Project Layout
```
├── Gemfile (must contain "gem 'sewing_kit")
├── package.json (must specify '@shopify/sewing-kit' as a 'devDependency')
│
└── app
   └── ui
   │   └─- index.js
   └── views
       └─- layouts
           └─- application.html.erb (must link to JS / CSS using sewing_kit_script_tag / sewing_kit_link_tag
```

## Rails, Polaris, and React Layout
A typical Polaris app will use React to render views and components.  The following layout shows best practice locations for:
- Global SCSS settings
- App sections (roughly analogous to Rails routes)
- Components
- Co-located CSS modules
- Co-located unit tests

```
└── app
    └── ui
        ├─- index.js (renders React into the DOM)
        ├── styles (optional)
        │   └── settings.scss (global vars and @polaris overrides)
        │
        └── components (optional)
            ├── App
            │   ├── index.js
            │   ├── App.js
            │   └── tests
            │       └── App.test.js
            │
            ├-─ MyComponent
            │   ├-─ index.js
            │   ├-─ MyComponent.js
            │   ├── MyComponent.scss (optional; component-scoped CSS styles, mixins, etc)
            │   └── tests
            │       └── MyComponent.test.js
            │
            └── sections (optional; container views that compose presentation components into UI blocks)
                └── Home
                    ├-─ index.js
                    └── Home.js
```

## Which version of sewing-kit can I use?
Assume that the sewing_kit gem's latest minor version requires _at least_ the same minor version of the sewing-kit package.

If sewing-kit makes a breaking change, this gem's minor version will be bumped to match the required sewing-kit version.

## Transitioning from sprockets-commoner
It is currently not recommended to use `sprockets-commoner` and `sewing_kit` in the same project.
Minimally, it is required that the project does not have its own `babel-*` libraries that `sewing-kit` currently has as [dependencies](https://github.com/Shopify/sewing-kit/blob/master/package.json#L97~L102).

## Build Pipeline Gotchas
While sewing-kit is a dev dependency, it is needed for production builds. This means that the production build will break if the environment variable `YARN_INSTALL` is set to true, because it will prevent `devDependencies` from being installed.

To work around this in Buildkite, set `YARN_PRODUCTION=false` in the Environment Variables section of Pipeline Settings:

![image](https://user-images.githubusercontent.com/2354121/36445473-64f6c4a2-164c-11e8-90fd-4e1b7835d7a2.png)

## React Boilerplate
* Create a React app in `app/ui/App.js` ([example](https://github.com/Shopify/rails_sewing_kit_example/blob/master/app/ui/App.jsx))
* In an `erb` view, add a placeholder for React content ([example](https://github.com/Shopify/rails_sewing_kit_example/blob/master/app/views/home/index.html.erb#L4))
* In `index.js`, render a React component into the placeholder element ([example](https://github.com/Shopify/rails_sewing_kit_example/blob/master/app/ui/index.js))
* Use `sewing_kit_script_tag`/`sewing_kit_link_tag` helpers to link erb/js ([example](https://github.com/Shopify/rails_sewing_kit_example/blob/master/app/views/layouts/application.html.erb#L8))