From 8d67820406601abf58cd8b543d83abc071ce6fe9 Mon Sep 17 00:00:00 2001 From: ZauberNerd Date: Thu, 12 Oct 2017 17:52:22 +0200 Subject: [PATCH] docs: update all readme files --- packages/build-config/readme.md | 10 ++-- packages/build/readme.md | 6 +-- packages/cli/readme.md | 10 ++-- packages/config/readme.md | 7 +-- packages/local-cli/readme.md | 6 +-- packages/server/readme.md | 2 +- packages/spec/readme.md | 4 ++ packages/template-react/readme.md | 90 +++++++++++++++++++++++++++++-- readme.md | 56 ++++++++++++------- 9 files changed, 147 insertions(+), 44 deletions(-) create mode 100644 packages/spec/readme.md diff --git a/packages/build-config/readme.md b/packages/build-config/readme.md index d2909058a..9fbbb96d1 100644 --- a/packages/build-config/readme.md +++ b/packages/build-config/readme.md @@ -3,7 +3,9 @@ hops-build-config exposes webpack configurations for Node.js, browser and webpack-dev-server. # Installation -When you install [hops-build](https://github.com/xing/hops/tree/master/packages/build), hops-build-config will be installed as a dependency as well - so you don't necessarily have to separately install hops-build-config. If you want to use it in your app directly, install it by running +When you install [hops-build](https://github.com/xing/hops/tree/master/packages/build), hops-build-config will be installed as a dependency as well - so you don't necessarily have to separately install hops-build-config. + +However iff you want to use it in your app directly (for example to extend it), install it by running ``` npm install --save hops-build-config @@ -21,7 +23,8 @@ Please find a list of the default configs below. If you use [hops-config](https: | `nodeConfig` | `String` | Path to your Webpack node/server-side rendering configuration file. Defaults to `./node_modules/hops-build-config/configs/node.js` | -## Overwrite configs via package.json +## Custom Webpack configuration +Webpack configurations can be nasty to handle, therefore we recommend using [webpack-merge](https://www.npmjs.com/package/webpack-merge) if you want to extend one of the existing Webpack configurations. The following example shows how to overwrite / extend the webpack configurations: @@ -86,6 +89,3 @@ PostCSS in Hops is configured to use [cssnext](http://cssnext.io/) and [CSS Modu | `png` `gif` `jpeg` `jpg` `webp` | Same as above, except when a file of this type is smaller than 10kb in size. In that case, it will be converted to a base64-encoded data URL and embedded inline in the referencing document | | `json` | Files of this type are loaded and their content is returned | | `tpl` | Files of this type are parsed by [_.template](https://lodash.com/docs/4.17.4#template) and their content is returned as a function. By providing such a file, you can override the default template provided by [hops-react](https://www.npmjs.com/package/hops-react) | - -## Custom Webpack configuration -Webpack configurations can be nasty to handle, therefore we recommend using [webpack-merge](https://www.npmjs.com/package/webpack-merge) if you want to extend one of the existing Webpack configurations. diff --git a/packages/build/readme.md b/packages/build/readme.md index 52a4b5fc0..b2cb5058c 100644 --- a/packages/build/readme.md +++ b/packages/build/readme.md @@ -1,7 +1,7 @@ # Hops Build -hops-build is a wrapper around webpack and [hops-build-config](https://github.com/xing/hops/tree/master/packages/build-config) which exports a function to execute a single build. +hops-build is a wrapper around webpack and [hops-build-config](https://github.com/xing/hops/tree/master/packages/build-config) which exports functions to execute a single build or start a `webpack-dev-server`. ### API @@ -16,7 +16,7 @@ If being used without the `static` option it will run the webpack build for the | Field | Type | Default | Description | |-------|------|---------|-------------| | static | boolean | `false` | Whether to statically build app shells for all locations | -| clean | boolean | `false` | Whether to clean the build and cache directories before starting the build | +| clean | boolean | `true` | Whether to clean the build and cache directories before starting the build | The `callback` is being called after the build has finished and can be used to schedule further work. @@ -28,7 +28,7 @@ It will take the `developConfig` with its `watchConfig` (see [hops-build-config] | Field | Type | Default | Description | |-------|------|---------|-------------| -| clean | boolean | `false` | Whether to clean the build and cache directories before starting the server | +| clean | boolean | `true` | Whether to clean the build and cache directories before starting the server | The `callback` is being called after the server has started and can be used to schedule further work. diff --git a/packages/cli/readme.md b/packages/cli/readme.md index 060b285ef..0d2a8aeef 100644 --- a/packages/cli/readme.md +++ b/packages/cli/readme.md @@ -6,7 +6,7 @@ hops-cli provides a `hops` binary that should be installed globally. This binary provides different commands based on the context in which it is called. If called inside a hops project it will delegate to the [hops-local-cli](https://github.com/xing/hops/tree/master/packages/local-cli) and provide the commands defined there. -If called outside of a hops project it will expose just a single command `init` which can be used to initialize a new hops project based on a template (by default it will use [hops-template-default](https://github.com/xing/hops/tree/master/packages/template-default)). +If called outside of a hops project it will expose just a single command `init` which can be used to initialize a new hops project based on a template (by default it will use [hops-template-react](https://github.com/xing/hops/tree/master/packages/template-react)). ## Installation @@ -22,12 +22,12 @@ hops init my-new-hops-project [--verbose] [--npm] [--template hops-template-*] ``` This will create a very basic hops example project that is ready to go. -These options are additional: +The following arguments are optional: * `--verbose` - to increase the verbosity of the output for debugging purposes * `--npm` - to force usage of `npm` instead of `yarn` even if yarn is available * `--template` - to specify a different template for the intial structure. - * available templates: `hops-template-default` + * available templates: + * [hops-template-react](https://github.com/xing/hops/tree/master/packages/template-react) + * [hops-template-minimal](https://github.com/xing/hops/tree/master/packages/template-minimal) Then `cd` into `my-new-hops-project` and execute `hops --help` again to see a list of supported commands. These commands are provided by [hops-local-cli](https://github.com/xing/hops/tree/master/packages/local-cli). - - diff --git a/packages/config/readme.md b/packages/config/readme.md index 49e85a8e8..436939180 100644 --- a/packages/config/readme.md +++ b/packages/config/readme.md @@ -3,8 +3,9 @@ hops-config exposes options to configure the other Hops packages and your own application. It is quite flexible and highly extensible. # Installation -When you use any of the other hops packages, it is highly likely that you need to install `hops-config` as a peerDependency yourself. -Please have a look at the package.json files of the other hops packages that you use or check your npm/yarn logs to see if you need to install hops-config as a peerDependency. + +In case you want to extend the configuration or access it from your server/browser code, you should explicitly add `hops-config` as a dependency to your project. +Otherwise it will be installed through the other hops packages and doesn't need to be installed directly. ``` npm install --save hops-config @@ -32,7 +33,7 @@ Please find a list of the default options below. They can be set in your project | `assets` | `Object literal` | The applications's `.js` and `.css` assets. Defaults to a getter function that returns the assets contained in the automatically generated `manifest.json` | | `extends` | `String` | Path to a baseline configuration (could be for example a node module or a project-specific file), allowing you join the current configuration with that baseline | -Everything matching `/(config|file|dir)s?$/i` will be treated as a filesystem path (or array thereof) and resolved relative to your app's root folder. This only applies if the respective value is not an absolute path already. +All keys matching `/(config|file|dir)s?$/i` will be treated as a filesystem path (or array thereof) and resolved relative to your app's root folder. This only applies if the respective value is not an absolute path already. ## Configure via package.json diff --git a/packages/local-cli/readme.md b/packages/local-cli/readme.md index 887ae6859..b22b6f6cc 100644 --- a/packages/local-cli/readme.md +++ b/packages/local-cli/readme.md @@ -28,16 +28,16 @@ yarn add hops-local-cli hops-local-cli only lists commands that are available through other hops packages. -So for example `hops build` and `hops develop` are only available if `hops-build` is installed as a dependency in your project ([`hops-template-default`](https://github.com/xing/hops/tree/master/packages/template-default) includes it by default). +So for example `hops build` and `hops develop` are only available if `hops-build` is installed as a dependency in your project ([`hops-template-react`](https://github.com/xing/hops/tree/master/packages/template-react) includes it by default). -The command `hops serve` is only available if `hops-express` is installed as a dependency in your project (also included in the default template). +The command `hops serve` is only available if `hops-express` is installed as a dependency in your project (also included in the default react template). And the command `hops start` is only available if both `hops-build` and `hops-express` are installed as dependencies. ## Configuration -hops-local-cli is being configured through [hops-config](https://github.com/xing/hops/tree/master/packages/config) which uses the npm config mechanism (read more at hops-config). +hops-local-cli is being configured through `hops-config` which uses the npm config mechanism (read more at [hops-config](https://github.com/xing/hops/tree/master/packages/config)). That means that you can run `hops` commands independently and they will use the configuration from your package.json file, you cannot overwrite these values through `npm config set ...` when running hops-local-cli standalone. For that to work you need to run the hops-local-cli through your package.json `scripts` fields. diff --git a/packages/server/readme.md b/packages/server/readme.md index 642088b86..2e8e29f45 100644 --- a/packages/server/readme.md +++ b/packages/server/readme.md @@ -7,7 +7,7 @@ express-like interfaces to register the hops-middleware. It also exports a simple middleware that takes care of rewriting the paths of incoming http requests based on the values set in hops-config. -*exports:* +#### Exports: - `rewritePath(request, response, next) => void` `rewritePath` is an express-style middleware that adds a trailing slash to the url of the incoming request. diff --git a/packages/spec/readme.md b/packages/spec/readme.md new file mode 100644 index 000000000..85e2adfe7 --- /dev/null +++ b/packages/spec/readme.md @@ -0,0 +1,4 @@ + +# Hops Spec + +Hops spec contains the integration test suites and mocks and is considered a "private" package that is only used during development to very that all modules work correctly. diff --git a/packages/template-react/readme.md b/packages/template-react/readme.md index 6f1442cdb..ada8dad8a 100644 --- a/packages/template-react/readme.md +++ b/packages/template-react/readme.md @@ -1,7 +1,89 @@ -# Hops Example +# Hops Template React -This folder contains an example hops project set up for development with [React](http://reactjs.com) and [React Router](https://react-router.now.sh) using the latest ECMAScript and CSS features. +This is a small example application showing [hops](https://github.com/xing/hops) in action. +It demonstrates how to use hops with react, redux, flow and jest. -Babel, PostCSS and hops itself are configured using only `package.json`. During a build, an `index.html` is being generated using the very same React components that are being used within the browser. +It has the following folder structure: +``` +├── flow-typed +├── node_modules +├── package.json +├── readme.md +└── src + ├── app.js + ├── counter + │   ├── actions.js + │   ├── constants.js + │   ├── counterContainer.js + │   ├── counter.js + │   ├── index.js + │   ├── reducer.js + │   └── spec + │   ├── actions.spec.js + │   ├── counterContainer.spec.js + │   ├── counter.spec.js + │   ├── reducer.spec.js + │   └── __snapshots__ + │   ├── counterContainer.spec.js.snap + │   └── counter.spec.js.snap + ├── home + │   ├── home.js + │   ├── index.js + │   ├── spec + │   │   ├── home.spec.js + │   │   └── __snapshots__ + │   │   └── home.spec.js.snap + │   └── styles.css + └── reducers.js +``` -Run this demo by `npm install`ing it and `npm start`ing it afterwards. +This example uses `hops-react` to render in the browser or on the server via the same entry file `src/app.js`. + +It contains a small example of the `react-router` with two routes: `/` (home) and `/counter`. + +You can customize it to your needs - or use it as a reference guide when creating your own hops react project. + + +## Package.json scripts + +### `npm start` / `yarn start` + +This command can be used to start a development server with hot-code reloading or to start a production server. + +* starting a development server: `npm start` +* starting a production server: `npm start --production` + +Before you start a production server you need to build your JS bundle files. + + +### `npm run build` / `yarn build` + +This command will generate the browser and server bundles that are required for deploying your code or running the production server through `npm start --production`. + +It can also be used to statically build HTML pages for all `locations` that are configured in the `"config"` section of the `package.json`. + +In this scenario it will iterate through the `locations` and render each location to a HTML document that will be placed in the `build/` folder. + +To make use of this execute `npm run build -- --static` or `yarn build --static`. + + +### `npm test` / `yarn test` + +This command will test your code with [jest](https://facebook.github.io/jest/) a testrunner by facebook that integrates nicely with react. + + +### `npm run flow` / `yarn flow` + +This command will run flow to typecheck your code and warn you about errors early on. + + +### (`postinstall`) + +This script isn't really meant to be executed by the user. Instead it will run every time that you install the project or a new dependency and download the latest type definitions from [flow-typed](https://github.com/flowtype/flow-typed) for all of your dependencies. + + +## Configuration + +Please refer to [hops-config](https://github.com/xing/hops/tree/master/packages/config) to see a list of all supported options. + +In this project we configure `babel` and `postcss` through the `"browsers"` field and we specify two loctions `/` and `/counter` through the `"locations"` hash. diff --git a/readme.md b/readme.md index 5477bca2f..3a61a7207 100644 --- a/readme.md +++ b/readme.md @@ -21,24 +21,35 @@ Hops is a modular development and build environment for universal ("isomorphic") Hops is designed to simplify getting started with modern frontend tooling. It streamlines [Webpack](https://webpack.js.org) and [Jest](https://facebook.github.io/jest/) configuration featuring [Babel](https://babeljs.io) and [PostCSS](http://postcss.org). +### Quick start + +If you just want to get started with hops + react you can execute the following command to initialize a small example app: +```shell +npm install -g hops-cli +hops init my-awesome-project +cd my-awesome-project +npm start +``` +This will start hops in development mode. Visit [http://localhost:8080](http://localhost:8080) to see your app in the browser and make some changes to the code in your editor to see it live-reloading. + +If you want to build the JS bundles for production, run `npm run build` in your terminal and to start a Node.js server just type in `npm start --production`. + + ### Installation Besides reasonably recent versions of [Node.js](https://nodejs.org/en/) and [npm](https://www.npmjs.com), hops has no global dependencies. If you need those, we recommend using [nvm](https://github.com/creationix/nvm) or similar. -If you want to go all in with hops, here's what you have to do and install to create a basic project..: +Install the `hops-cli` globally via npm `npm install --global hops-cli` or yarn `yarn global add hops-cli`: -```shell -mkdir foo && cd foo -npm init -y -npm install -S hops-cli hops-config \ - hops-react react react-dom react-helmet react-router react-router-dom \ - hops-redux redux redux-thunk react-redux -``` +### Project creation + +`hops init my-project` will create a directory called `my-project` and initialize an example react project inside it. -### Setup -After installing hops into your project, you need to set it up. This can be done within your project's `package.json` file. The relevant fields are shown below: +### Configuration + +Hops is configured via the `package.json`s `"config"` field (read more about it at [hops-config](https://github.com/xing/hops/tree/master/packages/config): ```javascript { @@ -66,7 +77,7 @@ Hops provides a runner that you can call from the scripts of your `package.json` For developing using hops, you can use any decent editor with up-to-date language support. Those without a favorite we recommend [Atom](https://atom.io), probably with the [linter](https://atom.io/packages/linter), [linter-eslint](https://atom.io/packages/linter-eslint) and [linter-stylelint](https://atom.io/packages/linter-stylelint) plugins. -Assuming you edited your `package.json` as outlined above, you can fire up a dev server or trigger a production build like so: +Assuming you edited your `package.json` as outlined above, you can fire up a dev or production server like so: ```shell npm start (--production) @@ -79,22 +90,29 @@ If called with the `--production` flag, a production mode server is launched. Ot Hops is quite modular, its component being independently published on npm. Its main building blocks, however, rely upon each other: -* [Hops CLI](https://github.com/xing/hops/tree/master/packages/cli) +* [Hops Build](https://github.com/xing/hops/tree/master/packages/build) +* [Hops Build Config](https://github.com/xing/hops/tree/master/packages/build-config) +* [Hops Global CLI](https://github.com/xing/hops/tree/master/packages/cli) * [Hops Config](https://github.com/xing/hops/tree/master/packages/config) +* [Hops Express](https://github.com/xing/hops/tree/master/packages/express) * [Hops Jest Preset](https://github.com/xing/hops/tree/master/packages/jest-preset) +* [Hops Local CLI](https://github.com/xing/hops/tree/master/packages/local-cli) * [Hops React](https://github.com/xing/hops/tree/master/packages/react) * [Hops Redux](https://github.com/xing/hops/tree/master/packages/redux) The following additional packages are rather low-level and you'll probably never need to install and use them directly. -* [Hops Transpiler](https://github.com/xing/hops/tree/master/packages/transpiler) * [Hops Middleware](https://github.com/xing/hops/tree/master/packages/middleware) -* [Hops Renderer](https://github.com/xing/hops/tree/master/packages/renderer) * [Hops Webpack Plugin](https://github.com/xing/hops/tree/master/packages/plugin) +* [Hops Renderer](https://github.com/xing/hops/tree/master/packages/renderer) +* [Hops Server](https://github.com/xing/hops/tree/master/packages/server) +* [Hops Transpiler](https://github.com/xing/hops/tree/master/packages/transpiler) ### Contributing +Hops uses [lerna](https://github.com/lerna/lerna) and [yarn](https://yarnpkg.com/en/) for development and publishing of the packages. Therefore it is required to have `yarn` globally available. + If you want to contribute to this project, create a fork of its [repository](https://github.com/xing/hops/fork) using the GitHub UI. Check out your new fork to your computer: ``` bash @@ -102,14 +120,11 @@ mkdir hops && cd $_ git clone git@github.com:user/hops.git . ``` -Afterwards, you can `npm install` Hops' own dev dependencies and start the included demo project and begin developing. +Afterwards, you can `yarn install` the required dependencies and then run `yarn bootstrap` to install the dependencies of all packages and link the packages together. -``` bash -npm install -npm start -``` +Using `yarn start` will execute the `start` script in the [hops-template-react](https://github.com/xing/hops/template-react) so that you can verify your changes in the browser. -Whenever you run ```npm start```, the hops packages used in the demo project are being re-installed locally. When you are finished, please do go ahead and create a [pull request](https://help.github.com/articles/creating-a-pull-request/). +When you are finished, please do go ahead and create a [pull request](https://help.github.com/articles/creating-a-pull-request/). Hops is entirely written in ECMAScript 5 and adheres to [semistandard](https://github.com/Flet/semistandard) code style. Please make sure your contribution does, too. @@ -119,6 +134,7 @@ Hops is entirely written in ECMAScript 5 and adheres to [semistandard](https://g * [Next](https://github.com/zeit/next.js/) * [Gatsby](https://github.com/gatsbyjs/gatsby) * [Backpack](https://github.com/palmerhq/backpack) +* [Create React App](https://github.com/facebookincubator/create-react-app) ### Thanks!