Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Initial docs for app profiling #1075

Merged
merged 8 commits into from
May 26, 2023
Merged

Initial docs for app profiling #1075

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
7a5d5a7
Initial docs for app profiling
marcins Mar 7, 2023
28e4acf
Update docs around usage/API
marcins Mar 8, 2023
a3b4142
Fix formatting of CLI tables
marcins Mar 16, 2023
e13d697
Fix typos
marcins Mar 16, 2023
521ea09
Merge remote-tracking branch 'origin/v2' into mszczepanski/profiling-…
marcins May 12, 2023
def552f
Rename app profiling -> tracing
marcins May 12, 2023
0878a4d
Revert prettier changes
devongovett May 26, 2023
794cced
Move after parcel api in navigation
devongovett May 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 34 additions & 33 deletions src/features/cli.md
View file
Open in desktop
mischnic marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -79,47 +79,48 @@ parcel

These parameters are supported by all Parcel commands.

| Format | Description |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--target [name]` | Specifies the targets to build. May be specified multiple times. See [Targets](/features/targets/). |
| `--dist-dir <dir>` | Output directory to write to when unspecified by targets. <br> Default value for the [`distDir`](/features/targets/#distdir) option in package.json `targets`. |
| `--public-url <url>` | The path prefix for absolute urls. <br> Default value for the [`publicUrl`](/features/targets/#publicurl) option in package.json `targets`. |
| `--no-source-maps` | Disables sourcemaps, <br> Overrides the [`sourceMap`](/features/targets/#sourcemap) option in package.json `targets`. |
| Format | Description |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --- |
| `--target [name]` | Specifies the targets to build. May be specified multiple times. See [Targets](/features/targets/). |
| `--dist-dir <dir>` | Output directory to write to when unspecified by targets. <br> Default value for the [`distDir`](/features/targets/#distdir) option in package.json `targets`. |
| `--public-url <url>` | The path prefix for absolute urls. <br> Default value for the [`publicUrl`](/features/targets/#publicurl) option in package.json `targets`. |
| `--no-source-maps` | Disables sourcemaps, <br> Overrides the [`sourceMap`](/features/targets/#sourcemap) option in package.json `targets`. |
| `--config <path>` | Specify which Parcel config to use. <br> Can be a file path or package name. Defaults to `@parcel/config-default`. See [Parcel configuration](/features/plugins/). |
| `--reporter <package name>` | Run the specified reporter plugin in addition to the ones specified in the `.parcelrc`. Can be specified multiple times. |
| `--log-level (none/error/warn/info/verbose)` | Sets the log level. |
| `--cache-dir <path>` | Sets the cache directory. Defaults to `.parcel-cache`. See [Caching](/features/development/#caching).
| `--no-cache` | Disables reading from the filesystem cache. See [Caching](/features/development/#caching). | |
| `--profile` | Profiles the build (a flamechart can be generated). |
| `-V, --version` | Outputs the version number. |
| `--reporter <package name>` | Run the specified reporter plugin in addition to the ones specified in the `.parcelrc`. Can be specified multiple times. |
| `--log-level (none/error/warn/info/verbose)` | Sets the log level. |
| `--cache-dir <path>` | Sets the cache directory. Defaults to `.parcel-cache`. See [Caching](/features/development/#caching). |
| `--no-cache` | Disables reading from the filesystem cache. See [Caching](/features/development/#caching). | |
| `--profile` | Runs a CPU Sampling profile during the build (a flamechart can be generated). |
| `--profile-application` | Runs an [Application Profile](/features/profiling) during the build. |
| `-V, --version` | Outputs the version number. |

### Parameters specific to `serve` and `watch`

| Format | Description |
| ------------------- | ------------------------------------------------------------------------------------- |
| `-p, --port <port>` | The port for the dev server and HMR (the default port is `process.env.PORT` or 1234). See [Dev server](/features/development/#dev-server). |
| `--host <host>` | Sets the host to listen on, defaults to listening on all interfaces |
| `--https` | Runs the dev server and HMR server over [HTTPS](/features/development/#https). |
| `--cert <path>` | Path to a certificate to use. See [HTTPS](/features/development/#https). |
| `--key <path>` | Path to a private key to use. See [HTTPS](/features/development/#https). |
| `--no-hmr` | Disables [hot reloading](/features/development/#hot-reloading). |
| `--hmr-port <port>` | The port for the HMR server (defaults to the dev server's port). See [Hot reloading](/features/development/#hot-reloading).
| `--hmr-host <host>` | The host for the HMR server (defaults to the dev server's host). See [Hot reloading](/features/development/#hot-reloading). |
| `--no-autoinstall` | Disables [auto install](/features/development/#auto-install). |
| `--watch-for-stdin` | Stop Parcel once stdin is closed. |
| Format | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `-p, --port <port>` | The port for the dev server and HMR (the default port is `process.env.PORT` or 1234). See [Dev server](/features/development/#dev-server). |
| `--host <host>` | Sets the host to listen on, defaults to listening on all interfaces |
| `--https` | Runs the dev server and HMR server over [HTTPS](/features/development/#https). |
| `--cert <path>` | Path to a certificate to use. See [HTTPS](/features/development/#https). |
| `--key <path>` | Path to a private key to use. See [HTTPS](/features/development/#https). |
| `--no-hmr` | Disables [hot reloading](/features/development/#hot-reloading). |
| `--hmr-port <port>` | The port for the HMR server (defaults to the dev server's port). See [Hot reloading](/features/development/#hot-reloading). |
| `--hmr-host <host>` | The host for the HMR server (defaults to the dev server's host). See [Hot reloading](/features/development/#hot-reloading). |
| `--no-autoinstall` | Disables [auto install](/features/development/#auto-install). |
| `--watch-for-stdin` | Stop Parcel once stdin is closed. |

### Parameters specific to `serve`

| Format | Description |
| ------------------ | ------------------------------------------------------------------------------ |
| Format | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `--open [browser]` | Automatically opens the entry in your browser. Defaults to the default browser. See [Dev server](/features/development/#dev-server). |
| `--lazy` | Only builds bundles requested by the dev server. See [Lazy mode](/features/development/#lazy-mode). |
| `--lazy` | Only builds bundles requested by the dev server. See [Lazy mode](/features/development/#lazy-mode). |

### Parameters specific to `build`

| Format | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--no-optimize` | Disables optimizations such as minification. <br> Overrides the [`optimize`](/features/targets/#optimize) option of package.json `targets`. See [Production](/features/production/). |
| `--no-scope-hoist` | Disables scope hoisting. <br> Overrides the [`scopeHoist`](/features/targets/#scopehoist) option of package.json `targets`. See [Scope hoisting](/features/scope-hoisting/).
| `--no-content-hash` | Disables content hashing of output file names. <br> Bundle names may still include hashes, but they will not change on each build. See [Content hashing](/features/production/#content-hashing). | |
| `--detailed-report [depth]` | Displays the largest 10 (number configurable with `depth`) assets per bundle in the CLI report. See [Detailed report](/features/production/#detailed-report). |
| Format | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --- |
| `--no-optimize` | Disables optimizations such as minification. <br> Overrides the [`optimize`](/features/targets/#optimize) option of package.json `targets`. See [Production](/features/production/). |
| `--no-scope-hoist` | Disables scope hoisting. <br> Overrides the [`scopeHoist`](/features/targets/#scopehoist) option of package.json `targets`. See [Scope hoisting](/features/scope-hoisting/). |
| `--no-content-hash` | Disables content hashing of output file names. <br> Bundle names may still include hashes, but they will not change on each build. See [Content hashing](/features/production/#content-hashing). | |
| `--detailed-report [depth]` | Displays the largest 10 (number configurable with `depth`) assets per bundle in the CLI report. See [Detailed report](/features/production/#detailed-report). |
122 changes: 61 additions & 61 deletions src/features/parcel-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Parcel API
eleventyNavigation:
key: features-parcel-api
title: 📚 Parcel API
order: 10
order: 11
---

The Parcel API can be used to programmatically run builds or watch a project for changes. It is the same API as is used by the Parcel CLI. Use the API when you need more flexibility, or need to integrate Parcel into another build system.
Expand All @@ -28,11 +28,11 @@ There are two required parameters:
{% samplefile "build.mjs" %}

```javascript
import {Parcel} from '@parcel/core';
import { Parcel } from "@parcel/core";

let bundler = new Parcel({
entries: 'a.js',
defaultConfig: '@parcel/config-default'
entries: "a.js",
defaultConfig: "@parcel/config-default",
});
```

Expand All @@ -49,17 +49,17 @@ You can also use the `defaultTargetOptions` to set values for [Targets](/feature
{% samplefile "build.mjs" %}

```javascript
import {Parcel} from '@parcel/core';
import { Parcel } from "@parcel/core";

let bundler = new Parcel({
entries: 'a.js',
defaultConfig: '@parcel/config-default',
mode: 'production',
entries: "a.js",
defaultConfig: "@parcel/config-default",
mode: "production",
defaultTargetOptions: {
engines: {
browsers: ['last 1 Chrome version']
}
}
browsers: ["last 1 Chrome version"],
},
},
});
```

Expand All @@ -72,12 +72,12 @@ When set to an array, the `targets` option can be used to specify which of the p
{% samplefile "build.mjs" %}

```javascript
import {Parcel} from '@parcel/core';
import { Parcel } from "@parcel/core";

let bundler = new Parcel({
entries: 'a.js',
defaultConfig: '@parcel/config-default',
targets: ['modern']
entries: "a.js",
defaultConfig: "@parcel/config-default",
targets: ["modern"],
});
```

Expand All @@ -90,24 +90,24 @@ Alternatively, `targets` may be set to an object, which will override any target
{% samplefile "build.mjs" %}

```javascript
import {Parcel} from '@parcel/core';
import { Parcel } from "@parcel/core";

let bundler = new Parcel({
entries: 'a.js',
defaultConfig: '@parcel/config-default',
mode: 'production',
entries: "a.js",
defaultConfig: "@parcel/config-default",
mode: "production",
targets: {
modern: {
engines: {
browsers: ['last 1 Chrome version']
}
browsers: ["last 1 Chrome version"],
},
},
legacy: {
engines: {
browsers: ['IE 11']
}
}
}
browsers: ["IE 11"],
},
},
},
});
```

Expand All @@ -122,15 +122,15 @@ Environment variables such as `NODE_ENV` may be set using the `env` option. This
{% samplefile "build.mjs" %}

```javascript
import {Parcel} from '@parcel/core';
import { Parcel } from "@parcel/core";

let bundler = new Parcel({
entries: 'a.js',
defaultConfig: '@parcel/config-default',
mode: 'production',
entries: "a.js",
defaultConfig: "@parcel/config-default",
mode: "production",
env: {
NODE_ENV: 'production'
}
NODE_ENV: "production",
},
});
```

Expand All @@ -145,18 +145,18 @@ By default, Parcel does not write any output to the CLI when you use the API. Th
{% samplefile "build.mjs" %}

```javascript
import {Parcel} from '@parcel/core';
import {fileURLToPath} from 'url';
import { Parcel } from "@parcel/core";
import { fileURLToPath } from "url";

let bundler = new Parcel({
entries: 'a.js',
defaultConfig: '@parcel/config-default',
entries: "a.js",
defaultConfig: "@parcel/config-default",
additionalReporters: [
{
packageName: '@parcel/reporter-cli',
resolveFrom: fileURLToPath(import.meta.url)
}
]
packageName: "@parcel/reporter-cli",
resolveFrom: fileURLToPath(import.meta.url),
},
],
});
```

Expand All @@ -171,15 +171,15 @@ Once you’ve constructed a `Parcel` instance, you can use it to build a project
{% samplefile "build.mjs" %}

```javascript
import {Parcel} from '@parcel/core';
import { Parcel } from "@parcel/core";

let bundler = new Parcel({
entries: 'a.js',
defaultConfig: '@parcel/config-default'
entries: "a.js",
defaultConfig: "@parcel/config-default",
});

try {
let {bundleGraph, buildTime} = await bundler.run();
let { bundleGraph, buildTime } = await bundler.run();
let bundles = bundleGraph.getBundles();
console.log(`✨ Built ${bundles.length} bundles in ${buildTime}ms!`);
} catch (err) {
Expand All @@ -200,11 +200,11 @@ To watch a project for changes and be notified of each rebuild, use the `watch`
{% samplefile "build.mjs" %}

```javascript
import {Parcel} from '@parcel/core';
import { Parcel } from "@parcel/core";

let bundler = new Parcel({
entries: 'a.js',
defaultConfig: '@parcel/config-default'
entries: "a.js",
defaultConfig: "@parcel/config-default",
});

let subscription = await bundler.watch((err, event) => {
Expand All @@ -213,10 +213,10 @@ let subscription = await bundler.watch((err, event) => {
throw err;
}

if (event.type === 'buildSuccess') {
if (event.type === "buildSuccess") {
let bundles = event.bundleGraph.getBundles();
console.log(`✨ Built ${bundles.length} bundles in ${event.buildTime}ms!`);
} else if (event.type === 'buildFailure') {
} else if (event.type === "buildFailure") {
console.log(event.diagnostics);
}
});
Expand All @@ -236,17 +236,17 @@ The development server is included in the default Parcel config. It can be enabl
{% samplefile "build.mjs" %}

```javascript
import {Parcel} from '@parcel/core';
import { Parcel } from "@parcel/core";

let bundler = new Parcel({
entries: 'a.js',
defaultConfig: '@parcel/config-default',
entries: "a.js",
defaultConfig: "@parcel/config-default",
serveOptions: {
port: 3000
port: 3000,
},
hmrOptions: {
port: 3000
}
port: 3000,
},
});

await bundler.watch();
Expand All @@ -267,25 +267,25 @@ This example writes its output into an in-memory file system, and logs the conte
{% samplefile "build.mjs" %}

```javascript
import {Parcel, createWorkerFarm} from '@parcel/core';
import {MemoryFS} from '@parcel/fs';
import { Parcel, createWorkerFarm } from "@parcel/core";
import { MemoryFS } from "@parcel/fs";

let workerFarm = createWorkerFarm();
let outputFS = new MemoryFS(workerFarm);

let bundler = new Parcel({
entries: 'a.js',
defaultConfig: '@parcel/config-default',
entries: "a.js",
defaultConfig: "@parcel/config-default",
workerFarm,
outputFS
outputFS,
});

try {
let {bundleGraph} = await bundler.run();
let { bundleGraph } = await bundler.run();

for (let bundle of bundleGraph.getBundles()) {
console.log(bundle.filePath);
console.log(await outputFS.readFile(bundle.filePath, 'utf8'));
console.log(await outputFS.readFile(bundle.filePath, "utf8"));
}
} finally {
await workerFarm.end();
Expand Down
Loading