docs(core): reformat doc with better code fences (#12581)

This commit is contained in:
Benjamin Cabanes 2022-10-13 15:31:42 -04:00 committed by GitHub
parent f4d9b3dc2e
commit 3de46d5dd6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
18 changed files with 66 additions and 80 deletions

View File

@ -33,7 +33,7 @@ Let's say we have a repo with two projects. There's a React app (`react-app`) th
In the root `nx.json` file, we can set the following `namedInputs`:
```jsonc
```jsonc {% fileName="nx.json" %}
{
"namedInputs": {
"sharedGlobals": ["{workspaceRoot}/babel.config.json"],
@ -60,7 +60,7 @@ These names are not hard-coded. You can add your own `namedInputs` or rename the
With these `namedInputs` in place, we can set default `inputs` for project targets in `nx.json`:
```jsonc
```jsonc {% fileName="nx.json" %}
{
"namedInputs": {
"sharedGlobals": [
@ -95,7 +95,7 @@ The `test` target cache is invalidated if test or production code is changed in
In the `ui-library` library, we have some `*.spec.tsx` files that we don't want to count as production files. We can modify the project configuration to account for this:
```jsonc
```jsonc {% command="ui-library/project.json" %}
{
"namedInputs": {
"production": [
@ -124,7 +124,7 @@ The `build` and `test` `inputs` do not need to be modified at the project level,
## Scenario 2: Generated Documentation Site
Lets say you have a repo with two projects, a `docs-site` app that contains all the code for rendering a documentation site and a `content` library that contains markdown files that are used as the content of the site.
Let's say you have a repo with two projects, a `docs-site` app that contains all the code for rendering a documentation site and a `content` library that contains markdown files that are used as the content of the site.
The `content` library has a node script `.ts` file that is used to check through the markdown files for internal broken links. The `test` target looks like this:

View File

@ -55,7 +55,7 @@ instance, we know that changing a `footer`'s spec file will not change the resul
We can define a more precise configuration as follows:
```json title="nx.json"
```json {% fileName="nx.json"%}
{
"namedInputs": {
"default": ["{projectRoot}/**/*"],
@ -86,7 +86,7 @@ For more information about modifying `inputs` and `namedInputs` for your own rep
Your targets can also depend on runtime values.
```json title="nx.json"
```json {% fileName="nx.json"%}
{
"targetDefaults": {
"build": {
@ -137,7 +137,7 @@ during a cache hit.
Nx also caches the files generated by a command. The list of files/folders is listed in the `outputs` property of the project's `package.json`:
```json title="package.json"
```json {% fileName="package.json"%}
{
"nx": {
"targets": {
@ -152,7 +152,7 @@ Nx also caches the files generated by a command. The list of files/folders is li
If the `outputs` property for a given target isn't defined in the project'
s `package.json` file, Nx will look at the `targetDefaults` section of `nx.json`:
```json title="nx.json"
```jsonc {% fileName="nx.json"%}
{
...
"targetDefaults": {
@ -186,7 +186,7 @@ npx nx run test --skip-nx-cache
The cache is stored in `node_modules/.cache/nx` by default. To change the cache location, update the `cacheDirectory` option for the task runner in `nx.json`:
```json
```json {% fileName="nx.json"%}
{
"tasksRunnerOptions": {
"default": {

View File

@ -6,7 +6,7 @@ Nx creates a graph of all the dependencies between projects in your workspace us
If the `myapp/package.json` file has this dependency:
```jsonc
```jsonc {% fileName="myapp/package.json"%}
{
"dependencies": {
"@myorg/awesome-library": "*"
@ -37,7 +37,7 @@ Nx creates a graph of all the dependencies between projects in your workspace us
{% tabs %}
{% tab label="package.json" %}
```jsonc
```jsonc {% fileName="package.json"%}
{
"name": "myapp",
"nx": {
@ -49,7 +49,7 @@ Nx creates a graph of all the dependencies between projects in your workspace us
{% /tab %}
{% tab label="project.json" %}
```jsonc
```jsonc {% fileName="project.json"%}
{
"root": "/libs/myapp",
"implicitDependencies": ["some-api"]
@ -59,4 +59,4 @@ Nx creates a graph of all the dependencies between projects in your workspace us
{% /tab %}
{% /tabs %}
Then `my-app` depends on `some-api`
Then `my-app` depends on `some-api`.

View File

@ -13,7 +13,7 @@ npx nx build myapp --parallel=5
Note, you can also change the default in `nx.json`, like this:
```json title="nx.json"
```json {% fileName="nx.json"%}
{
"tasksRunnerOptions": {
"default": {
@ -31,7 +31,7 @@ Note, you can also change the default in `nx.json`, like this:
To ensure tasks run in the correct order, Nx needs to know how the tasks depend on each other. Add the following to `nx.json`:
```json title="nx.json"
```jsonc {% fileName="nx.json"%}
{
...
"targetDefaults": {
@ -46,7 +46,7 @@ With this, Nx knows that before it can build a project, it needs to build all of
This mechanism is very flexible. Let's look at this example:
```json title="nx.json"
```jsonc {% fileName="nx.json"%}
{
...
"targetDefaults": {
@ -81,7 +81,7 @@ Situations like this are pretty common:
Because we described the rules in `nx.json`, they will apply to all the projects in the repo. You can also define
project-specific rules by adding them to the project's configuration.
```json
```jsonc {% fileName="nx.json"%}
{
...
"nx": {

View File

@ -31,14 +31,9 @@ the result of the test run.
Now, run the following command twice. The second time the operation will be instant:
```bash
nx test header
```
```bash title="Terminal Output"
```{% command="nx test header"%}
> nx run header:test [existing outputs match the cache, left as is]
> header@0.0.0 test
> jest
@ -51,7 +46,7 @@ Snapshots: 0 total
Time: 0.528 s, estimated 2 s
Ran all test suites.
————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
———————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
> NX Successfully ran target test for project header (4ms)

View File

@ -98,7 +98,7 @@ Next you should update your root lint configuration:
- If you are using **ESLint** you should look for an existing rule entry in your root `.eslintrc.json` called `"@nrwl/nx/enforce-module-boundaries"` and you should update the `"depConstraints"`:
```jsonc
```jsonc {% fileName=".eslintrc.json" %}
{
// ... more ESLint config here

View File

@ -18,7 +18,7 @@ Each project has the `test` and `build` targets defined. Tasks can be defined as
{% tabs %}
{% tab label="package.json" %}
```json
```json {% fileName="package.json" %}
{
"scripts": {
"build": "webpack -c webpack.conf.js",
@ -30,7 +30,7 @@ Each project has the `test` and `build` targets defined. Tasks can be defined as
{% /tab %}
{% tab label="project.json" %}
```json
```json {% fileName="project.json" %}
{
"targets": {
"build": {
@ -70,7 +70,7 @@ npx nx run-many --target=build
This will build the projects in the right order: `footer` and `header` and then `myapp`.
```bash title="Terminal Output"
```{% command="npx nx run-many --target=build" %}
✔ nx run header:build (501ms)
✔ nx run footer:build (503ms)
✔ nx run myapp:build (670ms)

View File

@ -12,7 +12,7 @@ One of the best features of Nx the ability to construct the project graph automa
You can register a plugin by adding it to the plugins array in `nx.json`:
```json
```jsonc {% fileName="nx.json" %}
{
...,
"plugins": [

View File

@ -12,7 +12,7 @@ Project inference plugins allow you to extend this functionality of Nx to other
You can register a plugin by adding it to the plugins array in `nx.json`:
```json
```jsonc {% fileName="nx.json" %}
{
...,
"plugins": [
@ -30,9 +30,7 @@ Project file patterns are used in two scenarios:
Let's use the below plugin and workspace layout as an example:
> libs/awesome-plugin/index.ts
```typescript
```typescript {% fileName="libs/awesome-plugin/index.ts" %}
export const projectFilePatterns = ['project.json', 'my-other-project-file'];
export function registerProjectTargets(projectFilePath) {
console.log(projectFilePath);
@ -51,7 +49,7 @@ my-workspace/
│ │ ├─ my-other-project-file
│ │ ├─ project.json
├─ nx.json
─ package.json
─ package.json
```

View File

@ -6,7 +6,7 @@ The generator below shows you how to generate a library, and then scaffold out a
First, you define a folder to store your static or dynamic templates used to generated files. This is commonly done in a `files` folder.
```treeview
```text
happynrwl/
├── apps/
├── libs/
@ -32,7 +32,7 @@ Hello, my name is <%= name %>!
Next, update the `index.ts` file for the generator, and generate the new files.
```typescript
```typescript {% fileName="index.ts" %}
import {
Tree,
formatFiles,
@ -73,7 +73,7 @@ nx generate my-generator mylib
The following information will be displayed.
```bash
```{% command="nx generate my-generator mylib" %}
CREATE libs/mylib/README.md
CREATE libs/mylib/.babelrc
CREATE libs/mylib/src/index.ts

View File

@ -11,7 +11,7 @@ export interface GeneratorOptions {
}
```
Import the TypeScript schema into your generator file and replace the any in your generator function with the interface.
Import the TypeScript schema into your generator file and replace the `any` in your generator function with the interface.
```typescript
import { Tree, formatFiles, installPackagesTask } from '@nrwl/devkit';
@ -108,7 +108,7 @@ Properties tagged with ⚠️ are required. Others are optional.
### Schema
```json
```jsonc
{
"properties": {
"name": {} // see Properties
@ -124,7 +124,7 @@ Properties tagged with ⚠️ are required. Others are optional.
The properties of a generator. Properties are listed by name:
```json
```jsonc
{
"properties_name": {
// properties configuration
@ -350,7 +350,7 @@ In this example, the property `a` is required, while the property `b` is optiona
Make sure that the value is in the enumeration. Example:
```json
```jsonc
{
"type": "string",
"enum": ["foo", "bar"]
@ -369,7 +369,6 @@ The sub-properties of a property. Example:
"index": {
"description": "Configures the generation of the application's HTML index.",
"type": "object",
"description": "",
"properties": {
"input": {
"type": "string",

View File

@ -83,7 +83,7 @@ third_party # nx will ignore everything in the third-party dir
After running `add-nx-to-monorepo` Nx will only analyze `package.json` files in the same way Lerna or Turborepo do.
```json
```json {% fileName="package.json" %}
{
"pluginsConfig": {
"@nrwl/js": {
@ -112,7 +112,7 @@ and require statements in your JS/TS files when creating its project graph. If y
property to the root `tsconfig.base.json` (if you don't have this file, create it), which will tell Nx how to resolve
imports.
```json
```json {% fileName="tsconfig.base.json" %}
{
"compilerOptions": {
"paths": {

View File

@ -52,8 +52,7 @@ npm i nx --save-dev
Change your `lerna.json` by adding the following flag.
```json
// lerna.json
```jsonc {% fileName="lerna.json" %}
{
...
"useNx": true
@ -66,8 +65,7 @@ By default `useNx` will be set to `false`, so you have to explicitly opt-in.
Nx works even without `nx.json` but to configure some more details such as the `cacheableOperations` of your monorepo in particular, create a `nx.json` at the root of the monorepo. Alternatively you can also just run `npx nx init` to have one generated. Specify the cacheable operations, usually something like `build`, `test`, `lint` etc, depending on your workspace setup:
```json
// nx.json
```json {% fileName="nx.json" %}
{
"extends": "nx/presets/npm.json",
"tasksRunnerOptions": {
@ -165,7 +163,7 @@ Nx comes with a whole range of additional features such as:
- **Interactive workspace visualization -** to interactively explore the underlying [project graph](/core-features/explore-graph) for understanding dependencies and find paths between nodes.
- **Nx plugins -** for adding first-class support for React, Next.js, React Native, Angular, Node, NestJS, Jest, Cypress, Storybook and many more.
- **Dedicated VSCode extension -** You can install [Nx Console](/core-features/integrate-with-editors) which is a dedicated VSCode extension to provide a visual interface for navigating your monorepo workspace in terms of launching commands as well as for generating code.
- **GitHub integration -** Install the [Nx Cloud Github App](https://github.com/apps/nx-cloud) to get inline reporting on your CI jobs.
- **GitHub integration -** Install the [Nx Cloud GitHub App](https://github.com/apps/nx-cloud) to get inline reporting on your CI jobs.
- ...
But take your time to explore.

View File

@ -18,7 +18,7 @@ npx create-nx-workspace@latest
Select `empty` when prompted:
```bash
```{% command="npx create-nx-workspace@latest" %}
? What to create in the new workspace (Use arrow keys)
empty [an empty workspace with a layout that works best for building apps]
```

View File

@ -89,7 +89,7 @@ This installs the `@nrwl/angular` (or `@nrwl/workspace`) package into your works
After the changes are applied, your workspace file structure should look similar to the one below:
```treeview
```text
<workspace name>/
├── apps/
│ ├── <app name>/
@ -207,7 +207,7 @@ When prompted for the `application name`, enter the _project name_ from your cur
A new Nx workspace with your `org name` as the folder name, and your `application name` as the first application is generated.
```treeview
```text
<workspace name>/
├── apps/
│ ├── <app name>/
@ -281,8 +281,7 @@ If you are using `Karma` for unit testing:
- Copy the `test` target in your `architect` configuration from your Angular CLI `angular.json` file into the `targets` configuration in the `apps/<app name>/project.json` file in your Nx workspace.
- Update the `test` target file paths to be relative to `apps/<app name>`.
```json
// apps/<app name>/project.json
```jsonc {% fileName="apps/<app name>/project.json" %}
{
"projectType": "application",
"sourceRoot": "apps/<app name>/src",
@ -312,7 +311,7 @@ If you are using `Karma` for unit testing:
- Update `test-setup.ts` to `test.ts` in the `files` array of the `apps/<app name>/tsconfig.spec.json` file.
```json
```json {% fileName="apps/<app name>/tsconfig.spec.json" %}
{
"extends": "./tsconfig.json",
"compilerOptions": {
@ -346,8 +345,7 @@ If you are using `Protractor` for E2E testing:
- Create the project configuration file at `apps/<app name>-e2e/project.json`.
- Copy the project configuration for `app name` from the Angular CLI workspace `angular.json` file to `apps/<app name>-e2e/project.json` and adjust the file paths to be relative to `apps/<app name>-e2e`.
```json
// apps/<app name>-e2e/project.json
```json {% fileName="apps/<app name>-e2e/project.json" %}
{
"projectType": "application",
"targets": {
@ -381,7 +379,7 @@ If you are using `Protractor` for E2E testing:
Create a `tsconfig.e2e.json` file under `apps/<app name>-e2e` folder:
```json
```json {% fileName="apps/<app name>-e2e/tsconfig.e2e.json" %}
{
"extends": "./tsconfig.json",
"compilerOptions": {
@ -392,7 +390,7 @@ Create a `tsconfig.e2e.json` file under `apps/<app name>-e2e` folder:
Update the `apps/<app name>/tsconfig.json` to extend the root `tsconfig.json`:
```json
```json {% fileName="apps/<app name>/tsconfig.json" %}
{
"extends": "../../tsconfig.json",
"compilerOptions": {

View File

@ -74,7 +74,7 @@ Copy the dependencies from the RealWorld apps `package.json` to the `package.
Your `package.json` should now look like this:
```json
```json {% fileName="package.json" %}
{
"name": "nx-migrate-angularjs",
"version": "0.0.0",
@ -219,7 +219,7 @@ During migration, you should take a small step and confirm that things work befo
Copy the `gulpfile.js` over from the RealWorld app and put it in `apps/realworld`. This is where all configuration files reside for the application. Make some adjustments to this file so that your build artifacts land in a different place. In an Nx workspace, all build artifacts should be sent to an app-specific folder in the `dist` folder at the root of your workspace. Your `gulpfile.js` should look like this:
```javascript
```javascript {% fileName="gulpfile.js" %}
var gulp = require('gulp');
var notify = require('gulp-notify');
var source = require('vinyl-source-stream');
@ -318,7 +318,7 @@ gulp.task('default', ['html', 'browserify'], function () {
You need to point your `build` and `serve` tasks at this gulp build process. Typically, an Angular app is built using the Angular CLI, but the Angular CLI doesnt know how to build AngularJS projects. All of your tasks are configured in the project configuration file `apps/realworld/project.json`. Find the `build` and `serve` tasks and replace them with this code block:
```json
```jsonc {% fileName="apps/realworld/project.json" %}
...
"build": {
"executor": "nx:run-commands",
@ -404,7 +404,7 @@ This webpack configuration is deliberately simplified for this tutorial. A real
To use webpack instead of gulp, go back to your `apps/realworld/project.json` file and modify the `build` and `serve` commands again:
```json
```jsonc {% fileName="apps/realworld/project.json" %}
...
"build": {
"executor": "@nrwl/web:webpack",
@ -509,7 +509,7 @@ In an example like this, its easy enough to make this kind of change by hand.
We also need to modify the `app.js` and remove the import of `config/app.templates.js`. Modify it like this:
```javascript
```javascript {% fileName="config/app.templates.js" %}
import angular from 'angular';
// Import our app config files
@ -627,7 +627,7 @@ module.exports = function (config) {
Next, rename the existing `apps/realworld/src/test.ts` to `apps/realworld/src/test.js` and modify its content to match the following:
```javascript
```javascript {% fileName="apps/realworld/src/test.js" %}
import 'angular';
import 'angular-mocks';
import 'angular-ui-router';
@ -692,8 +692,7 @@ Nx created `realworld-e2e` for you when you generated your app. There is an exam
You need to modify these files to account for the RealWorld app layout. Make the following modifications:
```typescript
//app.e2e-spec.ts
```typescript {% fileName="app.e2e-spec.ts" %}
import { AppPage } from './app.po';
import { browser, logging } from 'protractor';
@ -722,8 +721,7 @@ describe('workspace-project App', () => {
});
```
```typescript
// app.po.ts
```typescript {% fileName="app.po.ts" %}
import { browser, by, element } from 'protractor';
export class AppPage {
@ -739,7 +737,7 @@ export class AppPage {
You also need to modify the project configuration of the `realworld-e2e` app at `apps/realworld-e2e/project.json`. This will point your e2e process at the `development` configuration of the `realworld` app by default.
```json
```jsonc {% fileName="apps/realworld-e2e/project.json" %}
{
...
"e2e": {

View File

@ -200,7 +200,7 @@ module.exports = {
Update your app's `package.json` file (path: `apps/webapp/package.json`) to use `craco` instead of `react-scripts`.
```text
```text {% fileName="apps/webapp/package.json" %}
{
...
"scripts": {
@ -223,7 +223,7 @@ Your new project will use the `craco` scripts we added in `apps/webapp/package.j
In `apps/webapp/project.json` remove the `targets` object. The result will look like this:
```text
```json {% fileName="apps/webapp/project.json" %}
{
"root": "apps/webapp",
"sourceRoot": "apps/webapp/src",
@ -236,7 +236,7 @@ In `apps/webapp/project.json` remove the `targets` object. The result will look
Modify `apps/webapp/tsconfig.json` to extend the root `tsconfig.base.json`. This is primarily to pickup the typescript aliases from the root tsconfig file.
```json
```jsonc {% fileName="apps/webapp/tsconfig.json" %}
{
"extends": "../../tsconfig.base.json",
...
@ -300,7 +300,7 @@ nx generate lib ui-button
The new library can be used in your app like by adding this code to `App.tsx`:
```typescriptx
```typescriptx {% fileName="App.tsx" %}
//...
import { UiButton } from '@acme/ui-button';
//...

View File

@ -12,7 +12,7 @@ There are two main differences between an executor and a shell script or an npm
Executors are associated with specific targets in a project's `project.json` file.
```json
```jsonc {% fileName="project.json" %}
{
"root": "apps/cart",
"sourceRoot": "apps/cart/src",