# catalyst

> Sets up webpack, TypeScript, React, GraphQL, SASS, and more!

Latest version **2.0.0-beta.4** (published 2021-02-22) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install catalyst
pnpm add catalyst
yarn add catalyst
bun add catalyst
```

Provides the command `catalyst`.

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 2.0.0-beta.4 |
| Published | 2021-02-22 |
| First published | 2013-10-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >= 11.0.0 |
| Dependencies | 49 |
| Unpacked size | 112 KB |
| Known vulnerabilities | 0 (+7 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Dan Martens |
| Maintainers | danmartens |

## Links

- npm: https://www.npmjs.com/package/catalyst
- Repository: https://github.com/friendsoftheweb/catalyst
- Homepage: https://github.com/friendsoftheweb/catalyst#readme
- Issues: https://github.com/friendsoftheweb/catalyst/issues
- npm.io page: https://npm.io/package/catalyst

## Dependencies (49)

- [diff](https://npm.io/package/diff.md) ^4.0.1
- [sass](https://npm.io/package/sass.md) ^1.30.0
- [chalk](https://npm.io/package/chalk.md) ^4.1.0
- [debug](https://npm.io/package/debug.md) ^4.3.1
- [fibers](https://npm.io/package/fibers.md) ^5.0.0
- [lodash](https://npm.io/package/lodash.md) ^4.17.11
- [semver](https://npm.io/package/semver.md) ^7.3.4
- [postcss](https://npm.io/package/postcss.md) ^8.1.4
- [webpack](https://npm.io/package/webpack.md) ^5.11.0
- [inquirer](https://npm.io/package/inquirer.md) ^7.0.0
- [commander](https://npm.io/package/commander.md) ^6.2.0
- [babel-jest](https://npm.io/package/babel-jest.md) ^26.6.1
- [css-loader](https://npm.io/package/css-loader.md) ^5.0.1
- [image-size](https://npm.io/package/image-size.md) ^0.9.3
- [strip-ansi](https://npm.io/package/strip-ansi.md) ^6.0.0
- [@babel/core](https://npm.io/package/@babel/core.md) ^7.4.4
- [file-loader](https://npm.io/package/file-loader.md) ^6.2.0
- [sass-loader](https://npm.io/package/sass-loader.md) ^10.0.4
- [babel-loader](https://npm.io/package/babel-loader.md) ^8.0.6
- [find-process](https://npm.io/package/find-process.md) ^1.4.1
- [loader-utils](https://npm.io/package/loader-utils.md) ^2.0.0
- [schema-utils](https://npm.io/package/schema-utils.md) ^3.0.0
- [style-loader](https://npm.io/package/style-loader.md) ^2.0.0
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.4.4
- [postcss-loader](https://npm.io/package/postcss-loader.md) ^4.1.0
- [catalyst-client](https://npm.io/package/catalyst-client.md) ^2.0.0-beta.4
- [webpack-sources](https://npm.io/package/webpack-sources.md) ^2.2.0
- [@babel/preset-env](https://npm.io/package/@babel/preset-env.md) ^7.4.4
- [postcss-preset-env](https://npm.io/package/postcss-preset-env.md) ^6.7.0
- [webpack-dev-server](https://npm.io/package/webpack-dev-server.md) ^3.7.2
- [@babel/preset-react](https://npm.io/package/@babel/preset-react.md) ^7.0.0
- [babel-plugin-lodash](https://npm.io/package/babel-plugin-lodash.md) ^3.3.4
- [terser-webpack-plugin](https://npm.io/package/terser-webpack-plugin.md) ^5.0.3
- [workbox-webpack-plugin](https://npm.io/package/workbox-webpack-plugin.md) ^6.0.2
- [mini-css-extract-plugin](https://npm.io/package/mini-css-extract-plugin.md) ^1.2.1
- [webpack-bundle-analyzer](https://npm.io/package/webpack-bundle-analyzer.md) ^4.3.0
- [@babel/preset-typescript](https://npm.io/package/@babel/preset-typescript.md) ^7.3.3
- [circular-dependency-plugin](https://npm.io/package/circular-dependency-plugin.md) ^5.0.2
- [compression-webpack-plugin](https://npm.io/package/compression-webpack-plugin.md) ^7.1.0
- [css-minimizer-webpack-plugin](https://npm.io/package/css-minimizer-webpack-plugin.md) ^1.1.5
- [@babel/plugin-transform-runtime](https://npm.io/package/@babel/plugin-transform-runtime.md) ^7.4.4
- [@babel/plugin-syntax-dynamic-import](https://npm.io/package/@babel/plugin-syntax-dynamic-import.md) ^7.2.0
- [case-sensitive-paths-webpack-plugin](https://npm.io/package/case-sensitive-paths-webpack-plugin.md) ^2.2.0
- [@babel/plugin-proposal-class-properties](https://npm.io/package/@babel/plugin-proposal-class-properties.md) ^7.4.4
- [@babel/plugin-proposal-optional-chaining](https://npm.io/package/@babel/plugin-proposal-optional-chaining.md) ^7.2.0
- [duplicate-package-checker-webpack-plugin](https://npm.io/package/duplicate-package-checker-webpack-plugin.md) ^3.0.0
- [@babel/plugin-proposal-object-rest-spread](https://npm.io/package/@babel/plugin-proposal-object-rest-spread.md) ^7.4.4
- [babel-plugin-transform-react-remove-prop-types](https://npm.io/package/babel-plugin-transform-react-remove-prop-types.md) ^0.4.24
- [@babel/plugin-proposal-nullish-coalescing-operator](https://npm.io/package/@babel/plugin-proposal-nullish-coalescing-operator.md) ^7.4.4

## Recent versions

- 2.0.0-beta.4 (latest) — 2021-02-22
- 2.0.0-beta.14 (next) — 2021-09-13
- 1.0.0-beta.61 (beta) — 2019-11-01
- 2.0.0-beta.13 — 2021-09-13
- 2.0.0-beta.12 — 2021-09-13
- 2.0.0-beta.9 — 2021-09-13
- 2.0.0-beta.8 — 2021-09-13
- 2.0.0-beta.7 — 2021-05-28
- 2.0.0-beta.6 — 2021-03-05
- 2.0.0-beta.5 — 2021-03-03
- 2.0.0-beta.3 — 2021-02-22
- 2.0.0-beta.2 — 2021-01-15
- 1.2.0 — 2021-01-12
- 2.0.0-beta.1 — 2021-01-06
- 2.0.0-beta.0 — 2021-01-06
- … 76 more at https://npm.io/package/catalyst/versions

## README

# 🧪 Catalyst · ![CI](https://github.com/friendsoftheweb/catalyst/workflows/CI/badge.svg)

Catalyst is an opinionated tool for creating and maintaining React applications. It sets up webpack, TypeScript, React, Apollo, SASS, Autoprefixer, and more!

## Starting a New Project

```
$ yarn add catalyst
$ yarn run catalyst init
```

## Starting the Development Server

You can start the development server with:

```
$ NODE_ENV=development yarn run catalyst server
```

By default, the server will be accessible at http://localhost:8080. You can override this by setting
`DEV_SERVER_PROTOCOL`, `DEV_SERVER_HOST` and/or `DEV_SERVER_PORT` environment variables.

If you want to be able to access your development server from other devices on your local network,
you can start it like this:

```
$ DEV_SERVER_HOST=`ipconfig getifaddr en0` yarn start
```

Where "en0" is the identifier for the network device you're using.

## Integrating with Rails

See: https://github.com/friendsoftheweb/catalyst-rails

## Configuration

Certain aspects of Catalyst can be configured by editing the `catalyst.config.json` file in the root of your project. Some options can also be configured via environment variables (which take precedence over the value in `catalyst.config.json`). _The server must be restarted before any changes to the configuration will take effect._

| Key                                  | Environment Variable  | Type                                                     | Description                                                                                                                                                                                |
| ------------------------------------ | --------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **contextPath**                      | N/A                   | `string`                                                 | The path (relative to the root of your project) that webpack should treat as the [context](https://webpack.js.org/configuration/entry-context/#context) when requiring modules and assets. |
| **buildPath**                        | N/A                   | `string`                                                 | The path (relative to the root of your project) where _test_ and _production_ builds will be output.                                                                                       |
| **publicPath**                       | N/A                   | `string`                                                 | The the base URI used when generating paths for `<script />` and `<link />` tags.                                                                                                          |
| **importAssetsAsESModules**          | N/A                   | `boolean`                                                | If set to `false`, assets such as images and fonts will be imported in CommonJS format.                                                                                                    |
| **maxScriptAssetSizeKB**             | N/A                   | `number`                                                 | The maximum allowable size (in KB) for a script asset (post-optimization, but pre-compression).                                                                                            |
| **maxImageAssetSizeKB**              | N/A                   | `number`                                                 | The maximum allowable size (in KB) for an image asset (post-optimization).                                                                                                                 |
| **overlayEnabled**                   | N/A                   | `boolean`                                                | Display a custom overlay that shows build status, build errors, and runtime errors. This only applies to the _development_ environment.                                                    |
| **optimizationCommonMinChunks**      | N/A                   | `number`                                                 | The minimum number of chunks which must depend on a module for it to be included in the "common" chunk. Defaults to `2`.                                                                   |
| **optimizationCommonExcludedChunks** | N/A                   | `string[]`                                               | Names of chunks whose dependencies should be excluded from the "common" chunk. Defaults to `["admin", "administration", "management"]`.                                                    |
| **prebuiltPackages**                 | N/A                   | `string[]`                                               | A list of npm packages which should be pre-built in the _development_ environment. This decreases the time spent on re-building entries by skipping the listed packages.                   |
| **transformedPackages**              | N/A                   | `string[]`                                               | A list of npm packages which should be [transformed and polyfilled via Babel](https://babeljs.io/docs/en/babel-preset-env).                                                                |
| **checkForCircularDependencies**     | N/A                   | `boolean`                                                | Show warnings in _development_ and errors in other in environments if a circular dependency is detected.                                                                                   |
| **checkForDuplicatePackages**        | N/A                   | `boolean`                                                | Show warnings if multiple versions of the same package are required in the webpack dependency tree.                                                                                        |
| **ignoredDuplicatePackages**         | N/A                   | `string[]`                                               | A list of npm packages to ignore when checking for duplicates. This has no effect if **checkForDuplicatePackages** is `false`.                                                             |
| **devServerHost**                    | `DEV_SERVER_HOST`     | `string`                                                 | The host for the development server. Defaults to `"localhost"`.                                                                                                                            |
| **devServerPort**                    | `DEV_SERVER_PORT`     | `number`                                                 | The port for the development server. Defaults to `8080`.                                                                                                                                   |
| **devServerProtocol**                | `DEV_SERVER_PROTOCOL` | `string`                                                 | The protocol (e.g. `"http"` or `"https"`) used for accessing the development server. Defaults to `"http"`.                                                                                 |
| **devServerCertificate**             | N/A                   | `{ keyPath: string; certPath: string; caPath: string; }` | The certificate file paths for running the server with SSL support.                                                                                                                        |

### Configuring Webpack

Catalyst automatically creates a webpack configuration that should
be sufficient for most projects. If a project does require manual webpack configuration, a `webpack.config.js` file can be added to the root of the project.

Catalyst exports a function which returns Catalyst's default webpack configuration as an object:

```javascript
const { webpackConfig } = require('catalyst');

const customConfig = webpackConfig();

customConfig.module.rules.push({
  loader: 'my-custom-loader',
});

module.exports = customConfig;
```

### Analyzing Webpack Output

The size of the bundles output by webpack can be visualized using [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer). You can open the analyzer by starting Catalyst server with the `--bundle-analyzer` option:

```
$ NODE_ENV=development yarn run catalyst server --bundle-analyzer
```

## Using Catalyst

### Importing Images

Images can be imported as URLs via a standard ES import statement:

```js
import thisIsFineUrl from 'assets/images/this-is-fine.gif';

const Component = () => {
  return <img src={thisIsFineUrl} />;
};
```

The image's dimensions can also be imported as an object:

```js
import thisIsFineUrl, {
  dimensions as thisIsFineDimensions,
} from 'assets/images/this-is-fine.gif';

const Component = () => {
  return (
    <img
      src={thisIsFineUrl}
      width={thisIsFineDimensions.width}
      height={thisIsFineDimensions.height}
    />
  );
};
```

Make sure the assets TypeScript definitions have been added to your project (usually "client/assets.d.ts"). If they're missing, running `yarn run catalyst init` will add them to your project.

### Prefetching Important Assets

Catalyst has experimental support for generating a list of files to [prefetch](https://developer.mozilla.org/en-US/docs/Web/HTTP/Link_prefetching_FAQ) (via `<link rel="prefetch" />`). The files associated with any chunk which includes a JavaScript or TypeScript file with a `// @catalyst-prefetch` comment in it will be added to a `prefetch.json` file that's output during any non-development build.

This file can be used to generate link tags to allow important assets to be fetched before a user navigates to a part of the site that requires them. For example, to start loading the assets required for the checkout process before a user reaches the checkout process, a hypothetical "Checkout" component could be updated to include the `@catalyst-prefetch` directive:

```js
// @catalyst-prefetch

import React from 'react';

const Checkout = () => {
  return (
    // ...
  )
}
```

_NOTE:_ This will have no effect if the file is included in an "entry" chunk (i.e. the file is not part of a [dynamically imported](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Dynamic_Imports) chunk).

### Logging Apollo Client Errors During Development

Catalyst provides a global error logger method (`window.__CATALYST__.logger.error()`) that can be used to display an error message at the bottom of the browser window during development. This can be used to display GraphQL and network errors by adding a [custom "link"](https://www.apollographql.com/docs/react/data/error-handling/#network-errors) to your `@apollo/client` configuration:

```jsx
import { ApolloClient, HttpLink, from } from '@apollo/client';
import { onError } from '@apollo/client/link/error';

const link = from([
  onError(({ operation, graphQLErrors, networkError }) => {
    if (process.env.NODE_ENV === 'development') {
      if (networkError != null) {
        window.__CATALYST__?.logger?.error({
          location: operation.operationName,
          message: networkError.message,
        });
      }

      if (graphQLErrors != null) {
        for (const error of graphQLErrors) {
          window.__CATALYST__?.logger?.error({
            location: operation.operationName,
            message: error.message,
          });
        }
      }
    }
  }),
  new HttpLink({
    // ...
  }),
]);

const client = new ApolloClient({
  link,
  // ...
});
```

## Common Issues

### Requiring an MJS module causes the webpack build process to fail

If you see a message like this during a webpack build:

```
BREAKING CHANGE: The request './version' failed to resolve only because it was resolved as fully specified
(probably because the origin is a '*.mjs' file or a '*.js' file where the package.json contains '"type": "module"').
The extension in the request is mandatory for it to be fully specified.
Add the extension to the request.
```

You should make sure that every version of `@babel/runtime` used in your project
is at least `7.12.0`. You can check this by running `yarn why "@babel/runtime"`.
If any versions are lower than `7.12.0`, either update the parent dependency or
add `@babel/runtime` to the ["resolutions"](https://classic.yarnpkg.com/en/docs/selective-version-resolutions) section of your `package.json`.

---
_Source: https://npm.io/package/catalyst · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._