sewing_kit Build status

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

sewing_kit facilitates legacy Rails integration using ERB tags. For a more complete modern stack with performance-as-a-feature, consider quilt_rails. For details of the sewing-kit node package's configuration and usage, see the sewing-kit README.

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

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.

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

Configuring development mode

SewingKit.configure provides a development_options attribute that adjusts the behaviour of sewing-kit's development mode. See the dev command's documentation for a full list of options.

Usage

# config/initializers/sewing_kit.rb
SewingKit.configure do |config|
  # Disable hot module reloading
  config.development_options[:hot] = false

  # Launch development mode with extra memory (helpful if source maps are
  # occupying more than Node's default 1.4GB heap allocation)
  config.development_options[:heap] = 4000

  # Disable source maps (very large apps may need to builds sans source maps to
  # reduce development mode's memory usage)
  config.development_options[:source_maps] = false
end

Testing the front end

For fast tests with consistent results, test front-end components using Jest instead of Rails integration tests.

Use sewing-kit test to run all .test.tsx files in the app/ui directory. Jest is used as a test runner, with customization available via its sewing-kit plugin.

Customizing the test environment

Often you will want to hook up custom polyfills, global mocks, or other logic that needs to run either before the initialization of the test environment, or once for each test suite.

By default, sewing-kit will look for such test setup files under /app/ui/tests. Check out the documentation for more details.

Rails tests

Building JavaScript assets for Rails tests adds friction to test driven development, but some projects rely on tests that intermingle erb / JavaScript behaviour. To accommodate different test styles, sewing_kit offers two test modes.

:return_no_assets - sewing_kit helpers return empty arrays (default)

As noted above, the Web Foundation team highly recommends sewing-kit test for front end testing. Projects following this recommendation can use sewing_kit's default behaviour for controller, integration tests, and e2e tests. Note that no sewing_kit content will appear in pages with this mode enabled.

The default behaviour is equivalent to this configuration:

# config/initializers/sewing_kit.rb
SewingKit.configure do |config|
  config.test_manifest_mode = :return_no_assets
end

Use precompiled assets

If end-to-end tests are unavoidable:

  • Add extra steps to your test commands and CI pipelines that run sewing-kit build --mode test before test startup
  • Configure sewing_kit's test_manifest_mode to use precompiled assets:
# config/initializers/sewing_kit.rb
SewingKit.configure do |config|
  config.test_manifest_mode = :use_precompiled_assets
end

If your tests require production assets, precompile using sewing-kit build --mode production instead.

FAQ

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.

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 SK_SIMULATE_PRODUCTION=1 bundle exec rake assets:precompile
NODE_ENV=production SK_SIMULATE_PRODUCTION=1 dev run

Note:

  • Code changes will not be automatically recompiled in this state
  • SK_SIMULATE_PRODUCTION does not make Rails itself run in production mode
  • The most accurate way to gauge performance of the production version of an application is via a staging environment

After verifying production behaviour, run bundle exec rake assets:clobber to get back to development mode.

My project is using sprockets-commoner, can I use sewing_kit too?

No. sprockets-commoner uses an outdated Babel version, and is no longer compatible with sewing-kit.

sewing-kit's logs are too noisy. How can I see less of them?

sewing-kit defaults to using the same log_level as Rails' built in logger. It can be customized this using a configuration block:

SewingKit.configure do |config|
 config.log_level = :warn # may be `:inherit`, `:debug`, `:info`, `:warn`, or `:error`
end