diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 1dde172..66a5da6 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -3,6 +3,7 @@ * [Introduction](/README.md) * [Installation](/installation.md) * [Usage](/usage.md) +* [Project Layout](/project-layout.md) * [Presets](/presets/README.md) * [Web Preset](/presets/neutrino-preset-web/README.md) * [React Preset](/presets/neutrino-preset-react/README.md) diff --git a/docs/presets/neutrino-preset-jest/README.md b/docs/presets/neutrino-preset-jest/README.md new file mode 100644 index 0000000..48a7ad3 --- /dev/null +++ b/docs/presets/neutrino-preset-jest/README.md @@ -0,0 +1 @@ +# heading diff --git a/docs/presets/neutrino-preset-karma/README.md b/docs/presets/neutrino-preset-karma/README.md new file mode 100644 index 0000000..48a7ad3 --- /dev/null +++ b/docs/presets/neutrino-preset-karma/README.md @@ -0,0 +1 @@ +# heading diff --git a/docs/presets/neutrino-preset-mocha/README.md b/docs/presets/neutrino-preset-mocha/README.md new file mode 100644 index 0000000..48a7ad3 --- /dev/null +++ b/docs/presets/neutrino-preset-mocha/README.md @@ -0,0 +1 @@ +# heading diff --git a/docs/project-layout.md b/docs/project-layout.md new file mode 100644 index 0000000..42c3ca2 --- /dev/null +++ b/docs/project-layout.md @@ -0,0 +1,39 @@ +# Project Layout + +Out of the box Neutrino presets expect a project to have a particular structure in order to make the +development process for new projects as quick as possible. This is broken up into three directories: + +- Source code +- Build assets +- Testing + +Each of these directories are set up via convention by a Neutrino preset, but echo can be customized as +desired by overriding the preset's configuration or using a different preset. See +[Custom Configuration](#) for detailed instructions. + +## Source Code + +By default Neutrino presets expect all project source code to live in a directory named `src` in the +root of the project. This includes JavaScript files, CSS stylesheets, images, and any other assets +that would be available to your compiled project. + +When running your project or creating a build bundle, Neutrino will look for this `src` directory for +the entry point(s) to your application and use this as the relative location for finding other assets +necessary for creating your builds. + +## Build Assets + +When creating a build bundle, Neutrino presets will put the compiled assets, including any generated +JavaScript files, into a directory named `build` by default. Typically your Neutrino preset will copy +any non-JavaScript files from the source directory over to the build directory, allowing you to maintain +the same relative path structure for static assets as is used for the built assets. + +Normally most projects will exclude checking in this build directory to source control, e.g. git, hg, etc. +Be sure to add this directory to your project's `.gitignore`, `.hgignore`, or similar file. + +## Testing + +Neutrino presets expect all tests to be located in a directory named `test`. In order to make the +separation between tests and test fixtures or harnesses easier to differentiate, Neutrino presets also +usually look for test files ending in `_test.js` or `.test.js`. See your specific test preset for more +detailed information about running tests and other conventions. diff --git a/docs/usage.md b/docs/usage.md index 85712a9..e3038f0 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -15,22 +15,22 @@ In a typical project: - `scripts.test` would be the command you wish to run to execute tests Using these script targets may not be suitable for every project; know that they are just -typical recommendations for script target names, you may choose a different name if necessary +typical recommendations for script target names, you may choose a different name if desired for your project. ## Building for development Neutrino provides the command `neutrino start` for creating a bundle during development. Using `neutrino start` sets the Node.js environment to `development` using the `NODE_ENV` environment variable, -which is available in your project source code. Depending on the preset you are using, `neutrino start` +which is available in your project source code. Depending on the presets you are using, `neutrino start` may also spin up a development server with hot module reloading capabilities. -Check your preset for details. +Check the documentation of your preset for details. Usage: ```bash # PRESET_MODULE is the name of the preset to build with, e.g. neutrino-preset-react -neutrino start --preset PRESET_MODULE +neutrino start --presets PRESET_MODULE ``` Putting this into your `package.json` will allow you to build your project using either @@ -48,30 +48,78 @@ Putting this into your `package.json` will allow you to build your project using Neutrino provides the command `neutrino build` for creating a bundle for production deployment. Using `neutrino build` sets the Node.js environment to `production` using the `NODE_ENV` environment variable, -which is available in your project source code. +which is available in your project source code. See the documentation for your preset for details regarding additional +steps after your build is completed. ```bash # PRESET_MODULE is the name of the preset to build with, e.g. neutrino-preset-react -neutrino build --preset PRESET_MODULE +neutrino build --presets PRESET_MODULE ``` Putting this into your `package.json` will allow you to build your project using either -`yarn start` or `npm start`. Using `neutrino-preset-react` as an example: +`yarn build` or `npm run build`. Using `neutrino-preset-react` as an example: ```json { "scripts": { - "start": "neutrino build --preset neutrino-preset-react" + "build": "neutrino build --presets neutrino-preset-react" } } ``` ## Building and running tests -Neutrino provides the command `neutrino test` for creating a production bundle for use in executing tests. +Neutrino provides the command `neutrino test` for invoking a set of tests included in your project. Using `neutrino test` sets the Node.js environment variable to `test` using the `NODE_ENV` environment -variable, which is available in your project source code. +variable, which is available in your project source code. How your source code is built and consumed from tests +is determined by the preset your are using. Running suites that are built the same as source files are encouraged +to use a Neutrino-compatible preset. Neutrino currently provides three core testing presets: Karma, Jest, and Mocha. + +```bash +# PRESET_MODULE is the name of the preset to build with, e.g. neutrino-preset-react +# TESTING_MODULE is the name of another preset to build with, e.g. neutrino-preset-karma +neutrino build --presets PRESET_MODULE TESTING_MODULE +``` + +Putting this into your `package.json` will allow you to test your project using either +`yarn test` or `npm test`. Using `neutrino-preset-react` and `neutrino-preset-karma` as an example: +```json +{ + "scripts": { + "test": "neutrino test --presets neutrino-preset-react neutrino-preset-karma" + } +} +``` +Using the command `neutrino test` will execute every test file located in your +[testing directory](/project-layout#Testing). You may also provide to this command the specific test files you wish +to run individually. It is important to note that when combined with the `--presets` parameter, you should use two +dashes after the last preset to denote the end of the presets and the beginning of the test files. -## Default project layout +```bash +neutrino build --presets PRESET_A PRESET_B -- a_test.js b_test.js +``` + +## Using multiple presets + +All Neutrino commands support the `--presets` command line parameter, but having to specify this for each script target +can be cumbersome, especially if you have many presets. Fortunately Neutrino also supports specifying presets using the +`config.presets` field in your project's package.json file. By omitting the `--presets` flag and specifying a +`config.presets` array, every call to a Neutrino command will look up which presets are configured in your package.json. + +```json +{ + "config": { + "presets": [ + "neutrino-preset-react", + "neutrino-preset-karma" + ] + }, + "scripts": { + "start": "neutrino start", + "build": "neutrino build", + "test": "neutrino test" + } +} +```