diff --git a/templates/basic/README.md b/templates/basic/README.md index 7555d824d..c3d865fa5 100644 --- a/templates/basic/README.md +++ b/templates/basic/README.md @@ -1,27 +1,99 @@ -# TSDX Bootstrap +# TSDX User Guide -This project was bootstrapped with [TSDX](https://github.com/jaredpalmer/tsdx). +Congrats! You just saved yourself hours of work by bootstrapping this project with TSDX. Let’s get you oriented with what’s here and how to use it. -## Local Development +> This TSDX setup is meant for developing libraries (not apps!) that can be published to NPM. If you’re looking to build a Node app, you could use `ts-node-dev`, plain `ts-node`, or simple `tsc`. -Below is a list of commands you will probably find useful. +> If you’re new to TypeScript, checkout [this handy cheatsheet](https://devhints.io/typescript) -### `npm start` or `yarn start` +## Commands -Runs the project in development/watch mode. Your project will be rebuilt upon changes. TSDX has a special logger for you convenience. Error messages are pretty printed and formatted for compatibility VS Code's Problems tab. +TSDX scaffolds your new library inside `/src`. - +To run TSDX, use: -Your library will be rebuilt if you make edits. +```bash +npm start # or yarn start +``` -### `npm run build` or `yarn build` +This builds to `/dist` and runs the project in watch mode so any edits you save inside `src` causes a rebuild to `/dist`. -Bundles the package to the `dist` folder. -The package is optimized and bundled with Rollup into multiple formats (CommonJS, UMD, and ES Module). +To do a one-off build, use `npm run build` or `yarn build`. - +To run tests, use `npm test` or `yarn test`. -### `npm test` or `yarn test` +## Configuration -Runs the test watcher (Jest) in an interactive mode. -By default, runs tests related to files changed since the last commit. +Code quality is set up for you with `prettier`, `husky`, and `lint-staged`. Adjust the respective fields in `package.json` accordingly. + +### Jest + +Jest tests are set up to run with `npm test` or `yarn test`. + +#### Setup Files + +This is the folder structure we set up for you: + +```txt +/src + index.tsx # EDIT THIS +/test + blah.test.tsx # EDIT THIS +.gitignore +package.json +README.md # EDIT THIS +tsconfig.json +``` + +### Rollup + +TSDX uses [Rollup](https://rollupjs.org) as a bundler and generates multiple rollup configs for various module formats and build settings. See [Optimizations](#optimizations) for details. + +### TypeScript + +`tsconfig.json` is set up to interpret `dom` and `esnext` types, as well as `react` for `jsx`. Adjust according to your needs. + +## Continuous Integration + +### GitHub Actions + +A simple action is included that runs these steps on all pushes: + +- Installs deps w/ cache +- Lints, tests, and builds + +## Optimizations + +Please see the main `tsdx` [optimizations docs](https://github.com/palmerhq/tsdx#optimizations). In particular, know that you can take advantage of development-only optimizations: + +```js +// ./types/index.d.ts +declare var __DEV__: boolean; + +// inside your code... +if (__DEV__) { + console.log('foo'); +} +``` + +You can also choose to install and use [invariant](https://github.com/palmerhq/tsdx#invariant) and [warning](https://github.com/palmerhq/tsdx#warning) functions. + +## Module Formats + +CJS, ESModules, and UMD module formats are supported. + +The appropriate paths are configured in `package.json` and `dist/index.js` accordingly. Please report if any issues are found. + +## Named Exports + +Per Palmer Group guidelines, [always use named exports.](https://github.com/palmerhq/typescript#exports) Code split inside your React app instead of your React library. + +## Including Styles + +There are many ways to ship styles, including with CSS-in-JS. TSDX has no opinion on this, configure how you like. + +For vanilla CSS, you can include it at the root directory and add it to the `files` section in your `package.json`, so that it can be imported separately by your users and run through their bundler's loader. + +## Publishing to NPM + +We recommend using [np](https://github.com/sindresorhus/np). diff --git a/templates/react-with-storybook/README.md b/templates/react-with-storybook/README.md index c63cfdec7..be3a99082 100644 --- a/templates/react-with-storybook/README.md +++ b/templates/react-with-storybook/README.md @@ -1,8 +1,8 @@ -# TSDX React User Guide +# TSDX React w/ Storybook User Guide Congrats! You just saved yourself hours of work by bootstrapping this project with TSDX. Let’s get you oriented with what’s here and how to use it. -> This TSDX setup is meant for developing React components (not apps!) that can be published to NPM. If you’re looking to build an app, you should use `create-react-app`, `razzle`, `nextjs`, `gatsby`, or `react-static`. +> This TSDX setup is meant for developing React component libraries (not apps!) that can be published to NPM. If you’re looking to build a React-based app, you should use `create-react-app`, `razzle`, `nextjs`, `gatsby`, or `react-static`. > If you’re new to TypeScript and React, checkout [this handy cheatsheet](https://github.com/sw-yx/react-typescript-cheatsheet/) @@ -12,19 +12,19 @@ TSDX scaffolds your new library inside `/src`, and also sets up a [Parcel-based] The recommended workflow is to run TSDX in one terminal: -``` +```bash npm start # or yarn start ``` This builds to `/dist` and runs the project in watch mode so any edits you save inside `src` causes a rebuild to `/dist`. -Then run either example playground or storybook: +Then run either Storybook or the example playground: ### Storybook Run inside another terminal: -``` +```bash yarn storybook ``` @@ -36,13 +36,13 @@ This loads the stories from `./stories`. Then run the example inside another: -``` +```bash cd example npm i # or yarn to install dependencies npm start # or yarn start ``` -The default example imports and live reloads whatever is in `/dist`, so if you are seeing an out of date component, make sure TSDX is running in watch mode like we recommend above. **No symlinking required**, [we use Parcel's aliasing](https://github.com/palmerhq/tsdx/pull/88/files). +The default example imports and live reloads whatever is in `/dist`, so if you are seeing an out of date component, make sure TSDX is running in watch mode like we recommend above. **No symlinking required**, we use [Parcel's aliasing](https://parceljs.org/module_resolution.html#aliases). To do a one-off build, use `npm run build` or `yarn build`. @@ -50,17 +50,17 @@ To run tests, use `npm test` or `yarn test`. ## Configuration -Code quality is [set up for you](https://github.com/palmerhq/tsdx/pull/45/files) with `prettier`, `husky`, and `lint-staged`. Adjust the respective fields in `package.json` accordingly. +Code quality is set up for you with `prettier`, `husky`, and `lint-staged`. Adjust the respective fields in `package.json` accordingly. ### Jest -Jest tests are set up to run with `npm test` or `yarn test`. This runs the test watcher (Jest) in an interactive mode. By default, runs tests related to files changed since the last commit. +Jest tests are set up to run with `npm test` or `yarn test`. #### Setup Files This is the folder structure we set up for you: -``` +```txt /example index.html index.tsx # test your component here in a demo app @@ -82,7 +82,7 @@ We do not set up `react-testing-library` for you yet, we welcome contributions a ### Rollup -TSDX uses [Rollup v1.x](https://rollupjs.org) as a bundler and generates multiple rollup configs for various module formats and build settings. See [Optimizations](#optimizations) for details. +TSDX uses [Rollup](https://rollupjs.org) as a bundler and generates multiple rollup configs for various module formats and build settings. See [Optimizations](#optimizations) for details. ### TypeScript @@ -90,13 +90,12 @@ TSDX uses [Rollup v1.x](https://rollupjs.org) as a bundler and generates multipl ## Continuous Integration -### Travis - -_to be completed_ +### GitHub Actions -### Circle +A simple action is included that runs these steps on all pushes: -_to be completed_ +- Installs deps w/ cache +- Lints, tests, and builds ## Optimizations @@ -120,17 +119,7 @@ CJS, ESModules, and UMD module formats are supported. The appropriate paths are configured in `package.json` and `dist/index.js` accordingly. Please report if any issues are found. -## Using the Playground - -``` -cd example -npm i # or yarn to install dependencies -npm start # or yarn start -``` - -The default example imports and live reloads whatever is in `/dist`, so if you are seeing an out of date component, make sure TSDX is running in watch mode like we recommend above. **No symlinking required**! - -## Deploying the Playground +## Deploying the Example Playground The Playground is just a simple [Parcel](https://parceljs.org) app, you can deploy it anywhere you would normally deploy that. Here are some guidelines for **manually** deploying with the Netlify CLI (`npm i -g netlify-cli`): @@ -161,7 +150,7 @@ For vanilla CSS, you can include it at the root directory and add it to the `fil ## Publishing to NPM -We recommend using https://github.com/sindresorhus/np. +We recommend using [np](https://github.com/sindresorhus/np). ## Usage with Lerna diff --git a/templates/react/README.md b/templates/react/README.md index 33ce67704..cdb1f9d45 100644 --- a/templates/react/README.md +++ b/templates/react/README.md @@ -2,7 +2,7 @@ Congrats! You just saved yourself hours of work by bootstrapping this project with TSDX. Let’s get you oriented with what’s here and how to use it. -> This TSDX setup is meant for developing React components (not apps!) that can be published to NPM. If you’re looking to build an app, you should use `create-react-app`, `razzle`, `nextjs`, `gatsby`, or `react-static`. +> This TSDX setup is meant for developing React component libraries (not apps!) that can be published to NPM. If you’re looking to build a React-based app, you should use `create-react-app`, `razzle`, `nextjs`, `gatsby`, or `react-static`. > If you’re new to TypeScript and React, checkout [this handy cheatsheet](https://github.com/sw-yx/react-typescript-cheatsheet/) @@ -26,7 +26,7 @@ npm i # or yarn to install dependencies npm start # or yarn start ``` -The default example imports and live reloads whatever is in `/dist`, so if you are seeing an out of date component, make sure TSDX is running in watch mode like we recommend above. **No symlinking required**, [we use Parcel's aliasing](https://github.com/palmerhq/tsdx/pull/88/files). +The default example imports and live reloads whatever is in `/dist`, so if you are seeing an out of date component, make sure TSDX is running in watch mode like we recommend above. **No symlinking required**, we use [Parcel's aliasing](https://parceljs.org/module_resolution.html#aliases). To do a one-off build, use `npm run build` or `yarn build`. @@ -34,17 +34,17 @@ To run tests, use `npm test` or `yarn test`. ## Configuration -Code quality is [set up for you](https://github.com/palmerhq/tsdx/pull/45/files) with `prettier`, `husky`, and `lint-staged`. Adjust the respective fields in `package.json` accordingly. +Code quality is set up for you with `prettier`, `husky`, and `lint-staged`. Adjust the respective fields in `package.json` accordingly. ### Jest -Jest tests are set up to run with `npm test` or `yarn test`. This runs the test watcher (Jest) in an interactive mode. By default, runs tests related to files changed since the last commit. +Jest tests are set up to run with `npm test` or `yarn test`. #### Setup Files This is the folder structure we set up for you: -```shell +```txt /example index.html index.tsx # test your component here in a demo app @@ -66,7 +66,7 @@ We do not set up `react-testing-library` for you yet, we welcome contributions a ### Rollup -TSDX uses [Rollup v1.x](https://rollupjs.org) as a bundler and generates multiple rollup configs for various module formats and build settings. See [Optimizations](#optimizations) for details. +TSDX uses [Rollup](https://rollupjs.org) as a bundler and generates multiple rollup configs for various module formats and build settings. See [Optimizations](#optimizations) for details. ### TypeScript @@ -74,13 +74,12 @@ TSDX uses [Rollup v1.x](https://rollupjs.org) as a bundler and generates multipl ## Continuous Integration -### Travis +### GitHub Actions -_to be completed_ +A simple action is included that runs these steps on all pushes: -### Circle - -_to be completed_ +- Installs deps w/ cache +- Lints, tests, and builds ## Optimizations @@ -104,17 +103,7 @@ CJS, ESModules, and UMD module formats are supported. The appropriate paths are configured in `package.json` and `dist/index.js` accordingly. Please report if any issues are found. -## Using the Playground - -```bash -cd example -npm i # or yarn to install dependencies -npm start # or yarn start -``` - -The default example imports and live reloads whatever is in `/dist`, so if you are seeing an out of date component, make sure TSDX is running in watch mode like we recommend above. **No symlinking required**! - -## Deploying the Playground +## Deploying the Example Playground The Playground is just a simple [Parcel](https://parceljs.org) app, you can deploy it anywhere you would normally deploy that. Here are some guidelines for **manually** deploying with the Netlify CLI (`npm i -g netlify-cli`):