Document customization

README.md

@@ -7,6 +7,7 @@ Despite all the recent hype, setting up a new TypeScript (x React) library can b
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
+
 - [Features](#features)
 - [Quick Start](#quick-start)
   - [`npm start` or `yarn start`](#npm-start-or-yarn-start)
@@ -17,11 +18,15 @@ Despite all the recent hype, setting up a new TypeScript (x React) library can b
   - [Development-only Expressions + Treeshaking](#development-only-expressions--treeshaking)
     - [Rollup Treeshaking](#rollup-treeshaking)
     - [Advanced `babel-plugin-dev-expressions`](#advanced-babel-plugin-dev-expressions)
-      - [`__DEV__`](#dev)
+      - [`__DEV__`](#__dev__)
       - [`invariant`](#invariant)
       - [`warning`](#warning)
   - [Using lodash](#using-lodash)
   - [Error extraction](#error-extraction)
+- [Customization](#customization)
+  - [Rollup](#rollup)
+    - [Example: Adding Postcss](#example-adding-postcss)
+  - [Babel](#babel)
 - [Inspiration](#inspiration)
   - [Comparison to Microbundle](#comparison-to-microbundle)
 - [API Reference](#api-reference)
@@ -276,10 +281,81 @@ _This feature is still under development_
 
 After running `--extractErrors`, you will have a `./errors/codes.json` file with all your extracted error codes. This process scans your production code and swaps out your error message strings for a corresponding error code (just like React!). This extraction only works if your error checking/warning is done by a function called `invariant`. Note: you can use either `tiny-invariant` or `tiny-warning`, but you must then import the module as a variable called `invariant` and it should have the same type signature.
 
-After that, you will need to host the decoder somewhere (with the URL that you passed in to `--extractErrors`).
+After that, you will need to host the decoder somewhere. Look at `./errors/ErrorProd.js` and replace the URL with yours.
 
 _Simple guide to host error codes to be completed_
 
+## Customization
+
+### Rollup
+
+TSDX uses Rollup under the hood. The defaults are solid for most packages (Formik uses the defaults!). However, if you do wish to alter the rollup configuration, you can do so by creating a file called `tsdx.config.js` at the root of your project like so:
+
+```js
+// Not transpiled with TypeScript or Babel, so use plain Es6/Node.js!
+module.exports = {
+  // This function will run for each entry/format/env combination
+  rollup(config, options) {
+    return config; // always return a config.
+  },
+};
+```
+
+The `options` object contains the following:
+
+```tsx
+export interface TsdxOptions {
+  // path to file
+  input: string;
+  // Safe name (for UMD)
+  name: string;
+  // JS target
+  target: 'node' | 'browser';
+  // Module format
+  format: 'cjs' | 'umd' | 'esm';
+  // Environment
+  env: 'development' | 'production';
+  // Path to tsconfig file
+  tsconfig?: string;
+  // Is error extraction running?
+  extractErrors?: boolean;
+  // Is minifying?
+  minify?: boolean;
+  // Is this the very first rollup config (and thus should one-off metadata be extracted)?
+  writeMeta?: boolean;
+}
+```
+
+#### Example: Adding Postcss
+
+```js
+const postcss = require('rollup-plugin-postcss');
+const autoprefixer = require('autoprefixer');
+const cssnano = require('cssnano');
+
+module.exports = {
+  rollup(config, options) {
+    config.plugins.push(
+      postcss({
+        plugins: [
+          autoprefixer(),
+          cssnano({
+            preset: 'default',
+          }),
+        ],
+        inject: false,
+        // only write out CSS for the first bundle (avoids pointless extra files):
+        extract: !!options.writeMeta,
+      })
+    );
+    return config;
+  },
+};
+```
+### Babel
+
+You can add your own `.babelrc` to the root of your project and TSDX will **merge** it with its own babel transforms (which are mostly for optimization). 
+
 ## Inspiration
 
 TSDX is ripped out of [Formik's](https://github.com/jaredpalmer/formik) build tooling. TSDX is very similar to [@developit/microbundle](https://github.com/developit/microbundle), but that is because Formik's Rollup configuration and Microbundle's internals have converged around similar plugins over the last year or so.

src/types.ts

@@ -1,11 +1,20 @@
 export interface TsdxOptions {
+  // path to file
   input: string;
+  // Name of package
   name: string;
+  // JS target
   target: 'node' | 'browser';
+  // Module format
   format: 'cjs' | 'umd' | 'esm';
+  // Environment
   env: 'development' | 'production';
+  // Path to tsconfig file
   tsconfig?: string;
-  extractErrors?: string;
+  // Is error extraction running?
+  extractErrors?: boolean;
+  // Is minifying?
   minify?: boolean;
+  // Is this the very first rollup config (and thus should one-off metadata be extracted)?
   writeMeta?: boolean;
 }