# sewing_kit [![Build status](https://badge.buildkite.com/e7cdc87e61b9fe80e91e8686b6bfba53ca26a36366eb811a50.svg)](https://buildkite.com/shopify/sewing-kit-gem-ci)

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](/README.md).

## Quick Start

Create a Rails project using `dev init` then:

### Install Sewing Kits

```sh
# Add Ruby/Node dependencies
bundle add sewing_kit
yarn add @shopify/sewing-kit

# 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).

## React Boilerplate

- Create a React app in `app/ui/App.js` ([example](https://github.com/Shopify/sewing-kit-gem-example/blob/master/app/ui/App.jsx))
- In an `erb` view, add a placeholder for React content ([example](https://github.com/Shopify/sewing-kit-gem-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/sewing-kit-gem-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/sewing-kit-gem-example/blob/master/app/views/layouts/application.html.erb#L8))

## FAQ

### How can I fix production builds that are failing due to missing devDependencies?

By moving everything into `package.json#dependencies`. This is necessary because Rails 5.2 prunes `devDependencies` during asset compilation.

### How can I test a production verison of my changes?

Ideally, by deploying to a `staging` environment. If that is not possible, a production-like local development experience is available via:

```sh
NODE_ENV=production bundle exec rake assets:precompile
NODE_ENV=production SK_SIMULATE_PRODUCTION=1 dev run
```

Note that code changes will not be automatically recompiled in this state. After verifying production behaviour, run `bundle exec rake assets:clobber` to get back to development mode.