README.md in sewing_kit-0.95.2 vs README.md in sewing_kit-0.95.3
- old
+ new
@@ -2,10 +2,16 @@
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](https://github.com/Shopify/quilt/tree/master/gems/quilt_rails). For details of the `sewing-kit` node package's configuration and usage, see the [sewing-kit README](/README.md).
+## Use `quilt_rails` for React Server-Side-Rendering
+
+For React applications with a Rails backend, the best-practice for user-experience is server-side-rendering (SSR). **For building out React applications using SSR and Sewing-Kit, see [`quilt_rails`](https://github.com/Shopify/quilt/tree/master/gems/quilt_rails)**.
+
+If you are building a conventional Rails application using `.erb` files and just want modern JavaScript / TypeScript compilation, continue reading this document.
+
## Quick Start
Create a Rails project using `dev init` then:
### Install Sewing Kits
@@ -13,13 +19,10 @@
```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
@@ -49,138 +52,22 @@
└── 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)
- │
- └── tests (optional)
- │ └── each-test.ts
- │ └── setup.ts
- └── 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
-```
-
-## 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))
-
## 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`](https://github.com/Shopify/sewing-kit/blob/master/docs/commands/test.md#L3) to run all `.test.tsx` files in the `app/ui` directory. [Jest](https://jestjs.io) is used as a test runner, with customization available via [its sewing-kit plugin](https://github.com/Shopify/sewing-kit/blob/master/docs/plugins/jest.md).
-### Testing React
+### Customizing the test environment
-For testing React applications we provide and support [`@shopify/react-testing`](https://github.com/Shopify/quilt/tree/master/packages/react-testing).
+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.
-#### Example
+By default, sewing-kit will look for such test setup files under `/app/ui/tests`. Check out the [documentation](https://github.com/Shopify/sewing-kit/blob/master/docs/plugins/jest.md#smart-defaults) for more details.
-Given a component `MyComponent.tsx`
-
-```tsx
-// app/components/MyComponent/MyComponent.tsx
-export function MyComponent({name}: {name: string}) {
- return <div>Hello, {name}!</div>;
-}
-```
-
-A test would be written using Jest and `@shopify/react-testing`'s `mount` feature.
-
-```tsx
-// app/components/MyComponent/tests/MyComponent.test.tsx
-import {MyComponent} from '../MyComponent';
-
-describe('MyComponent', () => {
- it('greets the given named person', () => {
- const wrapper = mount(<MyComponent name="Kokusho" />);
-
- // toContainReactText is a custom matcher provided by @shopify/react-testing/matchers
- expect(wrapper).toContainReactText('Hello, Kokusho');
- });
-});
-```
-
-### Test setup files
-
-By default, the jest plugin will look for test setup files under `/app/ui/tests`.
-
-`setup` can be used to add any custom polyfills needed for the testing environment.
-
-```tsx
-// app/ui/tests/setup.ts
-
-import 'isomorphic-fetch';
-import 'raf/polyfill';
-import {URL, URLSearchParams} from 'url';
-
-(global as any).URL = URL;
-(global as any).URLSearchParams = URLSearchParams;
-```
-
-`each-test` can be used for any logic that needs to run for each individual test suite. Any setup logic that needs to happen with `jest` globals in scope, such as importing custom matchers, should also be done here.
-
-```tsx
-// app/ui/tests/each-test.ts
-
-// we cannot import these in `setup` because `expect` will not be defined
-import '@shopify/react-testing/matchers';
-
-beforeAll(() => {
- console.log('I will run before every test suite');
-});
-
-beforeEach(() => {
- console.log('I will run before every test case');
-});
-
-afterEach(() => {
- console.log('I will run after every test case');
-});
-
-afterAll(() => {
- console.log('I will run after every test suite');
-});
-```
-
-For more complete documentation of the jest plugin see [it's documentation](/docs/plugins/jest.md).
-
### 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)
@@ -251,14 +138,6 @@
```ruby
SewingKit.configure do |config|
config.log_level = :warn # may be `:inherit`, `:debug`, `:info`, `:warn`, or `:error`
end
-```
-
-### How can I set breakpoints for server rendered apps?
-
-Start your Rails server with `SK_DEBUG` set as an environment variable, and configure your Node debugger to listen on port `5858`.
-
-```bash
-SK_DEBUG=1 bundle exec rails start
```