@change-org/sandcastle

Sandcastle (Alpha)

Sandcastle is a node.js server for local development that uses dynamic Webpack configs to allow you to test your React components in a browser in isolation.

How it works

The short version

// sandcastle.js
const startSandcastle = require('path/to/sandcastle');
startSandcastle({ webpackConfig: require('./webpack.config.js) });

// in your shell
node sandcastle.js

To test components/MyComponent.jsx, simply load /components/MyComponent.jsx on the Sandcastle server. For example, for a Sandcastle server running on localhost with port 3141 (the default port), you would load http://localhost:3141/components/MyComponent.jsx in your browser.

The longer version

When you load /components/MyComponent.jsx, the Sandbox server creates an instance of the Webpack compiler that serves compiled JS using webpack-dev-middlware. Any requests for webpack assets from this page will connect to this same middleware so that content like hot module reloading data, source maps, dynamically-loaded chunks, and anything else served by webpack will re-use the same webpack compiler and middleware.

Sandcastle components and module resolution

Sandcastle will look in three places for the component you're testing. A __sandcastle__ folder in the same directory as your component can be used to set up props and any other dependencies for testing your component.

1. First, it looks for __sandcastle__/${componentFilename} in the component's directory.
2. If that file doesn't exist, it will look for __sandcastle__/${componentFilenameWithJsxExtension} in the component's directory.
3. If neither of those files exist, it will load the component from the path provided in the Sandcastle URL.

For example, if you're loading the TypeScript component components/MyTypescriptComponent.tsx, it will look for component files in this order.

1. components/__sandcastle__/MyTypescriptComponent.tsx
2. components/__sandcastle__/MyTypescriptComponent.jsx
3. components/MyTypescriptComponent.tsx

This allows you to create a Sandcastle component that sets your component up for testing in the same language as the component or as a jsx file (or use the original component if your component does not require setup).

Environment

Sandcastle can use an Environment component to set up depenencies common to all components you'll be testing. This is useful for setting up React context providers so that you can use context consumers in the components you're testing. The props for your Environment component are set up using an environment setup function (except for children, which depends on the component and layout being rendered). The path to the Environment component module is set with the environment config option.

Environment setup

You can define a module that's used to set up the props for your Environment component. This module exports a function that will be run once when initially loading the sandbox page to create the environment props. It can be an asynchronous function if you need to do any asynchronous work to initialize the environment such as HTTP requests. The path to the environment setup module is set with the setupEnvironment config option.

Layouts

When initializing Sandcastle, you can provide a layouts object that maps layout names to file paths containing layout modules.

A layout module should export a React component with ony a children prop.

To use a layout in Sandcastle, use the layout query param to select a layout name. If no layout query param is present, the layout under the default key will be used. If no layouts are defined, the component will be renderd as-is on the page.

It may be useful to create a layout that centers a component for more pleasant development, and another with no margins or padding for components that take up the full page.

You may find it useful to use query params inside of layouts for more options (e.g. a background color).

API

startSandcastle(sandcastleOptions)

Starts the sandcastle server.

Example usage (with default options):

const startSandcastle = require('@change/sandcastle');

startSandcastle({
  webpackConfig: undefined,
  port: 3141,
  webpackPath: '__sandcastle_webpack',
  hotMiddlewarePath: '__webpack_hmr',
  sandcastleComponentFolder: '__sandcastle__',
  environment: undefined,
  setupEnvironment: undefined,
  bootstrap: undefined,
  webpackDefine: {},
  layouts: {},
});

sandcastleOptions

• webpackConfig (required): The webpack config object to extend when creating Webpack middleware.
• port (optional): the port to run the sandcastle server on. Default: 3141.
• webpackPath (optional): The path under which to serve webpack content on the Sandcastle server. Default: '__sandcastle_webpack'.
• hotMiddlewarePath (optional): The path under the webpackPath under which to receive hot reload events. Default: '__webpack_hmr'.
• sandcastleComponentFolder (optional): If you want to use a directory name other than __sandcastle__ for storing Sandcastle components, you can specify an alternative name here. Default: '__sandcastle__'.
• environment (optional): Path to a module exporting an environment component.
• setupEnvironment (optional): Path to a module exporting a function that creates the props for the environment component.
• bootstrap (optional): Path to a module run before all other code on the Sandcastle client. Can be used to set up polyfills and other global dependencies.
• webpackDefine (optional): Config object for Webpack's DefinePlugin for inserting data in to the client bundle. Can be useful to make server data (such as configuration) available on the client for use in layouts or environment files. Default: {}.
• layouts (optional): Map of layout names to paths to their files. Default: {}.

The following options can be passed as a function to allow a change in configuration depending on the path of the file loaded. The function will be called with the relative path to the component file requested.

• webpackConfig
• environment
• setupEnvironment
• bootstrap
• webpackDefine