sewing_kit Build status

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.

Quick Start

Create a Rails project using dev init then:

Install Sewing Kits

# 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:

<%= 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

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

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.

React Boilerplate

  • Create a React app in app/ui/App.js (example)
  • In an erb view, add a placeholder for React content (example)
  • In index.js, render a React component into the placeholder element (example)
  • Use sewing_kit_script_tag/sewing_kit_link_tag helpers to link erb/js (example)

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:

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.