diff --git a/sources/@repo/docs/_redirects b/sources/@repo/docs/_redirects deleted file mode 100644 index 8111d9a688..0000000000 --- a/sources/@repo/docs/_redirects +++ /dev/null @@ -1,7 +0,0 @@ -http://budjs.netlify.app/* https://bud.js.org/:splat 301! -https://budjs.netlify.app/* https://bud.js.org/:splat 301! -https://bud.js.org/blog/tags/release https://bud.js.org/releases 301! -https://bud.js.org/blog/* https://bud.js.org/releases/:splat 301! -https://bud.js.org/dev/api https://bud.js.org/docs 301! -https://bud.js.org/guides/general-use/multi-compiler https://bud.js.org/guides/general-use/multi-instance 301! -https://bud.js.org/guides/general-use/transpiler-sources https://bud.js.org/guides/general-use/compiler-sources 301! diff --git a/sources/@repo/docs/config/docusaurus.theme.cjs b/sources/@repo/docs/config/docusaurus.theme.cjs index 1641851ab9..82a4e9974e 100644 --- a/sources/@repo/docs/config/docusaurus.theme.cjs +++ b/sources/@repo/docs/config/docusaurus.theme.cjs @@ -1,12 +1,13 @@ const dracula = require(`prism-react-renderer/themes/dracula`) const config = require(`../../../../config/monorepo.config.cjs`) +const releaseData = require(`../generated/releases/data.json`) /** - * Announcement bar config + * Color mode */ -const announcementBar = { - content: `Support bud.js on github sponsors`, - id: `announcementBar-5`, // Increment on change +const colorMode = { + disableSwitch: true, + respectPrefersColorScheme: true, } /** @@ -16,52 +17,6 @@ const footer = { copyright: `Copyright © ${new Date().getFullYear()} ${ config.organization.name }.`, - links: [ - { - items: [ - { - label: `Getting started`, - to: `/guides/getting-started/`, - }, - { - label: `Configuration`, - to: `/docs/config/`, - }, - { - label: `Extensions`, - to: `/extensions/`, - }, - ], - title: `Links`, - }, - { - items: [ - { - href: config.organization.twitter, - label: `Twitter`, - }, - { - href: config.url.discourse, - label: `Discourse`, - }, - ], - title: `Community`, - }, - { - items: [ - { - label: `Releases`, - to: `/releases`, - }, - { - href: config.url.web, - label: `GitHub`, - }, - ], - title: `More`, - }, - ], - style: `dark`, } /** @@ -105,15 +60,15 @@ const navbar = { hideOnScroll: true, items: [ { - docId: `index`, - docsPluginId: `guides`, - label: `Guides`, + docId: `getting-started/index`, + docsPluginId: `learn`, + label: `Learn`, position: `left`, type: `doc`, }, { - href: `/docs/config`, - label: `Docs`, + href: `/reference/bud.after`, + label: `Reference`, position: `left`, }, { @@ -124,39 +79,40 @@ const navbar = { type: `doc`, }, { - items: [ - {label: `latest`, to: `/releases/tags/6-14`}, - {label: `6.13`, to: `/releases/tags/6-13`}, - {label: `6.12`, to: `/releases/tags/6-12`}, - {label: `6.11`, to: `/releases/tags/6-11`}, - {label: `6.9`, to: `/releases/tags/6-9`}, - {label: `6.8`, to: `/releases/tags/6-8`}, - {label: `6.7`, to: `/releases/tags/6-7`}, - {label: `6.6`, to: `/releases/tags/6-6`}, - {label: `6.5`, to: `/releases/tags/6-5`}, - {label: `6.4`, to: `/releases/tags/6-4`}, - ], + items: releaseData.reduce((items, release, i) => { + if (i === 0) { + return [ + ...items, + {label: `Latest`, to: `/releases/${release.semver}`}, + ] + } + if (release.patch === 0) { + return [ + ...items, + { + label: release.semver, + to: `/releases/tags/${release.major}-${release.minor}`, + }, + ] + } + return items + }, []), label: `Releases`, position: `left`, to: `/releases`, }, { - className: `header-github-link`, - href: `/dev`, - label: `Dev`, - position: `right`, - }, - { + 'aria-label': `Discourse`, className: `header-discourse-link`, href: config.url.discourse, - label: `Community`, + label: ` `, position: `right`, }, { - 'aria-label': `GitHub repository`, + 'aria-label': `GitHub`, className: `header-github-link`, href: config.url.web, - label: `GitHub`, + label: ` `, position: `right`, }, ], @@ -176,7 +132,7 @@ const prism = { } module.exports = { - announcementBar, + colorMode, footer, metadata, navbar, diff --git a/sources/@repo/docs/config/index.cjs b/sources/@repo/docs/config/index.cjs index 04f5a50303..2cec4cf337 100644 --- a/sources/@repo/docs/config/index.cjs +++ b/sources/@repo/docs/config/index.cjs @@ -11,7 +11,7 @@ const pluginSearch = require.resolve(`docusaurus-lunr-search`) const docsPath = path => resolve(__dirname, `..`, path ?? ``) -const sidebarPath = docsPath(`sidebars/docs.cjs`) +const sidebarPath = docsPath(`sidebars/reference.cjs`) const remarkPlugins = [[npm2yarn, {sync: true}]] @@ -45,24 +45,12 @@ module.exports = { pluginDocs, { editUrl: join(config.url.web, `edit/main/sources/@repo/docs/`), - id: `dev`, + id: `learn`, include: [`**/*.md`, `**/*.mdx`], - path: docsPath(`content/dev`), + path: docsPath(`content/learn`), remarkPlugins, - routeBasePath: `dev`, - sidebarPath: docsPath(`sidebars/sidebar.cjs`), - }, - ], - [ - pluginDocs, - { - editUrl: join(config.url.web, `edit/main/sources/@repo/docs/`), - id: `guides`, - include: [`**/*.md`, `**/*.mdx`], - path: docsPath(`content/guides`), - remarkPlugins, - routeBasePath: `guides`, - sidebarPath: docsPath(`sidebars/guides.cjs`), + routeBasePath: `learn`, + sidebarPath: docsPath(`sidebars/learn.cjs`), }, ], [ @@ -93,8 +81,9 @@ module.exports = { }, docs: { editUrl: join(config.url.web, `edit/main/sources/@repo/docs/`), - path: docsPath(`content/docs`), + path: docsPath(`content/reference`), remarkPlugins, + routeBasePath: `reference`, sidebarPath, }, pages: { diff --git a/sources/@repo/docs/content/dev/index.md b/sources/@repo/docs/content/dev/index.md deleted file mode 100644 index b6a2c43973..0000000000 --- a/sources/@repo/docs/content/dev/index.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Developer contribution guide -description: Be a pal. Contribute to bud. -sidebar_label: Introduction -slug: / ---- - -:::info - -This is a work-in-progress. - -::: - -How to get started with **bud.js** locally. - -## Installation - -- Clone [roots/bud](https://github.com/roots/bud) -- Run `yarn`. This will install all the dependencies and build everything out. - -Make sure you're using the exact version of node used in the repo. If you use [Volta](https://volta.sh) to manage Node versions this will be handled for you automatically, - -## Repo structure - -For the most part public packages are found in `sources/@roots`. - -Private packages are found in `sources/@repo`. The `config` directory contains most configuration files that support it. - -`storage` contains various artifacts and caches for tooling used in the repo, not tracked in version control. - -## @bud cli - -Development is aided by the @bud cli. Common tasks should be included in this documentation but you can run `yarn @bud` to see examples sourced from all the development subcommands. - -The `@bud` cli source code is found in `sources/@repo`. - -## Development - -You can start up tsc, vitest and docusaurus in `watch` mode with one command: - -```sh -yarn @bud dev -``` - -## Building - -Run `yarn @bud tsc` to build all tsc managed paths. Ensure packages are fully rebuilt with the force flag: `yarn @bud tsc --force`. - -## Testing - -Tests are run with [vitest](https://vitest.dev). - -### Unit testing - -```sh -yarn @bud test unit -``` - -Unit tests are co-located with the package they test, in a directory named `test`. - -### Integration testing - -Note that the `run` argument is mandatory for running integration tests (integration tests do not support `watch` mode). - -```sh -yarn @bud test run integration -``` - -All integration tests are located in `tests/integration`. - -### e2e testing - -Note that the `run` argument is mandatory for running e2e tests (e2e tests do not support `watch` mode). - -```sh -yarn @bud test run e2e -``` - -All e2e tests are located in `tests/e2e`. - -## Linting - -Run eslint: - -```sh -yarn @bud lint -``` - -Run prettier: - -```sh -yarn @bud lint format -``` - -Lint for package duplication: - -```sh -yarn @bud lint dependencies -``` - -Validate package.json and package exports: - -```sh -yarn @bud lint exports -``` - -## Using the local registry - -The local package registry is initialized when you install from monorepo root. - -After installation, you should see the registry running at [http://localhost:4873](http://localhost:4873). - -You can manually start and stop the registry like so: - -```sh -yarn @bud registry start -yarn @bud registry stop -``` - -### Publishing to the registry - -You can do a local release to the registry and install it from other projects running on your machine. - -To release: - -```sh -yarn @bud release --tag latest -``` - -After the release finishes, you can install it to any project in your dev environment using the `--registry` flag: - -```sh -yarn add @roots/bud@latest --dev --registry http://localhost:4873 -``` - -### Rebuilding packages - -If you want to make a change and try it again, first clean the existing packages and then rerun the release: - -```sh -yarn @bud registry clean -yarn @bud build --force -yarn @bud release --tag latest -``` - -## Documentation - -**bud.js** documentation is generated with [docusaurus](https://docusaurus.io/). - -The `yarn @bud docs` command will build all documentation and README. - -### READMEs - -Don't edit package README files directly. They are generated and your work will be overwritten. - -Each package supports a `docs` directory. Contents of files in the `docs` directory will be concatenated and merged in the package readme. - -### Site docs - -Site docs can be found in the `sources/@repo/docs/content` directory. - -Extension docs may have markdown sourced from the package's `docs` directory. You'll see an import at the top of the documentation, if so. This is so docs can be reused in the package README and the site documentation. - -## Updating contributors - -The `package.json` contributors field for all packages in `sources/@roots` can be updated like so: - -```sh -yarn workspace @repo/markdown-kit node contributors/index.js -``` diff --git a/sources/@repo/docs/content/extensions/bud-preset-wordpress/index.mdx b/sources/@repo/docs/content/extensions/bud-preset-wordpress/index.mdx index 707f25580d..cbbff38fdd 100644 --- a/sources/@repo/docs/content/extensions/bud-preset-wordpress/index.mdx +++ b/sources/@repo/docs/content/extensions/bud-preset-wordpress/index.mdx @@ -17,7 +17,6 @@ It includes the following extensisons: - [@roots/bud-postcss](/extensions/bud-postcss) - [@roots/bud-react](/extensions/bud-react) - [@roots/bud-entrypoints](/extensions/bud-entrypoints) -- [@roots/bud-wordpress-manifests](/extensions/bud-wordpress-manifests) - [@roots/wordpress-hmr](/extensions/bud-preset-wordpress/editor-integration) ## Installation diff --git a/sources/@repo/docs/content/extensions/bud-wordpress-manifests.mdx b/sources/@repo/docs/content/extensions/bud-wordpress-manifests.mdx deleted file mode 100644 index ec8f1c2ca4..0000000000 --- a/sources/@repo/docs/content/extensions/bud-wordpress-manifests.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: '@roots/bud-wordpress-manifests' -description: 'Include wordpress dependencies in entrypoints.json' -sidebar_label: '@roots/bud-wordpress-manifests' ---- - -Installs the following extensions: - -- [@roots/bud-entrypoints](bud-entrypoints.mdx) -- [@roots/bud-wordpress-dependencies](https://github.com/roots/bud/tree/main/sources/@roots/bud-wordpress-dependencies) -- [@roots/bud-wordpress-externals](https://github.com/roots/bud/tree/main/sources/@roots/bud-wordpress-externals) - -## Installation - -```npm2yarn -npm install @roots/bud-wordpress-manifests --save-dev -``` - -## Usage - -After installation you'll find any wordpress dependencies utilized in an entrypoint incorporated into `entrypoints.json` under a new `dependencies` key. - -Example: - -```json title="entrypoints.json" -{ - "entrypoint-a": { - "js": ["runtime.js", "entrypoint-a.js"], - "css": ["entrypoint-a.css"], - "dependencies": ["jquery", "lodash", "wp-i18n"] - } -} -``` - -You can use this information to load wordpress dependencies in [wp_enqueue_scripts](https://developer.wordpress.org/reference/hooks/wp_enqueue_scripts/) or [admin_enqueue_scripts](https://developer.wordpress.org/reference/hooks/admin_enqueue_scripts/). diff --git a/sources/@repo/docs/content/guides/configure/assets.mdx b/sources/@repo/docs/content/guides/configure/assets.mdx deleted file mode 100644 index 22c2ed6461..0000000000 --- a/sources/@repo/docs/content/guides/configure/assets.mdx +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Assets -sidebar_label: Assets ---- - -## Application entrypoints - -bud.js uses the concept of "entrypoints" to group application scripts and styles. Entrypoints are defined using [bud.entry](/docs/bud.entry). - -You can think of an entrypoint as a "page" in your application. Each entrypoint will have its own output file. - -If you only have a single entrypoint then it is enough to just pass the filename: - -```js title=bud.config.js -export default async bud => { - bud.entry('app') // src/app.js -} -``` - -If you have more than one file to include in the bundle, you can use an array: - -```js title=bud.config.js -export default async bud => { - bud.entry(['app.js', 'global.css']) -} -``` - -If you have additional entrypoints you may call [bud.entry](/docs/bud.entry) multiple times. - -But, it might be preferable to use an object: - -```js title=bud.config.js -export default async bud => { - bud.entry({ - app: ['app.js', 'global.css'], - landing: ['landing.js', 'landing.css'], - }) -} -``` - -There is still more that this function can do, but for our overview this is more than enough. You can learn more about this and -other details in the [bud.entry documentation](/docs/bud.entry). - -## Copying static assets - -The [bud.assets](/docs/bud.assets) function is used to copy files to the output directory. - -The simplest way to use it is to pass an array of directories (relative to [your project `@src` directory](#project-paths)) you would like to copy: - -```js title=bud.config.js -export default async bud => { - bud.assets(['images', 'fonts']) -} -``` - -If you want more control over the directory being output to, you can use an array of from/to pairs: - -```js title=bud.config.js -export default async bud => { - bud.assets([ - ['images', 'assets/images'], // from `@src/images` to `@dist/assets/images` - ['fonts', 'assets/fonts'], // from `@src/fonts` to `@dist/assets/fonts` - ]) -} -``` - -For complete control, you can pass an object: - -```js title=bud.config.js -export default async bud => { - bud.assets({ - from: bud.path(`@src`, 'images'), - to: bud.path(`@dist`, 'images', `@name`), // `@name` is the filename (including hash if applicable) - context: bud.path(`@src`), - noErrorOnMissing: true, - toType: `template`, - }) -``` - -:::info No need to copy imported assets - -If you are already including assets by importing them in a script or stylesheet, you do not need -to copy them explicitly. For example, given this stylesheet, copying `@src/fonts/MyFont.woff2` would be unnecessary: - -```js title='index.css' -@font-face { - font-family: 'MyFont'; - src: url(@src/fonts/MyFont.woff2) format('woff2'); -} -``` - -::: - -You can learn more about this and other details in the [bud.assets documentation](/docs/bud.assets). diff --git a/sources/@repo/docs/content/guides/configure/bud.config.js.mdx b/sources/@repo/docs/content/guides/configure/bud.config.js.mdx deleted file mode 100644 index 4eae048b58..0000000000 --- a/sources/@repo/docs/content/guides/configure/bud.config.js.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Basics -sidebar_label: Basics -description: Creating a bud.config.js file and running a build ---- - -Create a `bud.config.js` file. - -### An example config - -```js title=bud.config.js -/** - * Build configuration for bud.js - * @param {import('@roots/bud').Bud} bud - */ -export default async bud => { - /** - * The bud.js instance - */ - bud - /** - * Set the project source directory - */ - .setPath(`@src`, `sources`) - - /** - * Set the application entrypoints - * These paths are expressed relative to the `@src` directory - */ - .entry({ - app: [`app.js`, `app.css`], // [`./sources/app.js`, `./sources/app.css`] - }) - - /** - * Copy static assets from `sources/static` to `dist/static` - */ - .assets({ - from: bud.path(`@src/static`), - to: bud.path(`@dist/static`), - }) -} -``` - -To use `import`/`export` syntax and take advantage of ESM-only packages, we recommend setting `{"type": "module"}` package.json. - -The documentation on this site assumes users are using modular JavaScript. - -## Running the build - -Once you have configured your project the simplest way to actually run the compiler it is using the `bud build` command: - -### In production - -```bash npm2yarn -npm run bud build production -``` - -### In development - -```bash npm2yarn -npm run bud build development -``` - -`ctrl+c` will terminate the application when running in `development` mode. diff --git a/sources/@repo/docs/content/guides/configure/editor-integration.mdx b/sources/@repo/docs/content/guides/configure/editor-integration.mdx deleted file mode 100644 index 3a65693919..0000000000 --- a/sources/@repo/docs/content/guides/configure/editor-integration.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: IDE integration -sidebar_label: IDE integration ---- - -## tsconfig.json - -You can integrate with your IDE using a `jsconfig.json` or `tsconfig.json` file. - -There are base configs provided for you to extend: - -- [@roots/bud/config/jsconfig.json](https://github.com/roots/bud/tree/main/sources/@roots/bud/config/jsconfig.json) -- [@roots/bud/config/tsconfig.json](https://github.com/roots/bud/tree/main/sources/@roots/bud/config/tsconfig.json) - -### Example - -```json title=tsconfig.json -{ - "extends": "@roots/bud/config/tsconfig.json", - "compilerOptions": { - "paths": { - "@src/*": ["./src/*"] - }, - "types": ["@roots/bud-postcss", "@roots/bud-swc"] - }, - "files": ["bud.config.js"], - "include": ["src"], - "exclude": ["node_modules", "dist"] -} -``` - -### Notes - -- Add any extensions you are using to `compilerOptions.types` so that you're IDE can will pick up on the types. -- Add any [aliases](/docs/bud.alias) you are using to `compilerOptions.paths` so that your IDE can resolve them. -- Make sure `bud.config.js` is included in the `include` array so that your IDE will apply discovered types to the config file. - -## Intellisense for `bud.config.js` - -Add the following tsdoc comment directly above the exported config function: - -```js title=bud.config.js -/** @param {import('@roots/bud').Bud} bud */ -export default async bud => {} -``` diff --git a/sources/@repo/docs/content/guides/configure/extensions.mdx b/sources/@repo/docs/content/guides/configure/extensions.mdx deleted file mode 100644 index 36453fc763..0000000000 --- a/sources/@repo/docs/content/guides/configure/extensions.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Extensions -sidebar_label: Extensions ---- - -## Adding extensions - -**bud.js** is designed to be extended. Extensions which are downloaded as packages should be automatically instantiated and registered -along with **bud.js**. So, if you want to use React, you can simply install [@roots/bud-react](/extensions/bud-react) and your project will be ready to use JSX. - -If you want to add your own extensions after **bud.js** has bootstrapped, you can do so using [bud.use](/docs/bud.use). - -```js title=bud.config.js -import {BudExtension} from './extensions' - -export default async bud => { - bud.use([BudExtension]) -} -``` - -## Adding Webpack plugins - -In addition to supporting ad-hoc extensions, [bud.use](/docs/bud.use) supports any off-the-shelf webpack plugin: - -```js title=bud.config.js -import WebpackBar from 'webpackbar' - -export default async bud => { - bud.use([new WebpackBar()]) -} -``` diff --git a/sources/@repo/docs/content/guides/configure/optimizing.mdx b/sources/@repo/docs/content/guides/configure/optimizing.mdx deleted file mode 100644 index f35264ebbd..0000000000 --- a/sources/@repo/docs/content/guides/configure/optimizing.mdx +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Optimization -sidebar_label: Optimization ---- - -There are a number of optional optimizations you can perform on your application. - -## File hashing - -Use the [bud.hash](/docs/bud.hash) function to generate a hash for each file in the bundle. This hash will be added to outputted files. - -```js title=bud.config.js -export default async bud => { - bud.hash() -} -``` - -## Minimizing code - -Use the [bud.minimize](/docs/bud.minimize) function to run your application code through a minifier. - -```js title=bud.config.js -export default async bud => { - bud.minimize() -} -``` - -## Creating a runtime - -You may create an application runtime using [bud.runtime](/docs/bud.runtime). Using the `single` option is probably -the simplest and best solution for most applications: - -```js title=bud.config.js -export default async bud => { - bud.runtime('single') -} -``` - -## Creating a vendor chunk - -You can perform general code splitting with [bud.splitChunks](/docs/bud.splitChunks). - -```js title=bud.config.js -export default async bud => { - bud.splitChunks() -} -``` - -## Overriding the generated configuration - -At the end of the day, you may find yourself needing to override the config. You may do so using the **bud.override** function. - -The most versatile way to do this is using a callback function: - -```js title=bud.config.js -export default async bud => { - bud.config(config => ({ - ...config, - output: { - ...config.output, - filename: 'scripts/[name].js', - }, - })) -} -``` diff --git a/sources/@repo/docs/content/guides/configure/paths.mdx b/sources/@repo/docs/content/guides/configure/paths.mdx deleted file mode 100644 index 9704ac4598..0000000000 --- a/sources/@repo/docs/content/guides/configure/paths.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Paths -sidebar_label: Paths ---- - -## Setting application paths - -[bud.setPath](/docs/bud.setPath) is used to set project source and output paths. - -```js title=bud.config.js -export default async bud => { - /* Set the source path.*/ - bud.setPath('@src', 'source') - /* Set the output path.*/ - bud.setPath('@dist', 'build') -} -``` - -The `@src` and `@dist` handles are special handles associated with the input and output base directories. - -## Referencing application paths - -Once set, paths can be referenced using [bud.path](/docs/bud.path). - -```js title=bud.config.js -export default async bud => { - bud.path('@src') // absolute path to app source - bud.path('@dist') // absolute path to app output -} -``` - -## Reserved paths - -**bud.js** has a few path handles which fulfill a special role. - -| handle | description | default | -| ------------ | -------------------------------- | ---------------- | -| **@src** | source directory | `./src` | -| **@dist** | destination directory | `./dist` | -| **@storage** | cache/artifact storage directory | `./.budfiles` | -| **@modules** | modules directory | `./node_modules` | - -These paths can be overridden but should not be removed or hijacked for a purpose that differs from what is described. - -## Globbing - -[bud.glob](/docs/bud.glob) is a built-in globbing utility that can be used to generate a list of files matching a given pattern. - -This function is asychronous (returns a promise) and can be used in conjunction with `await`. - -```js title=bud.config.js -export default async bud => { - await bud.glob('@src', '**/*.js') // returns an array of absolute paths -} -``` - -There is a synchronous version available as well: [bud.globSync](/docs/bud.globSync). - -```js title=bud.config.js -export default async bud => { - bud.globSync('@src', '**/*.js') // returns an array of absolute paths -} -``` diff --git a/sources/@repo/docs/content/guides/general-use/config-layers.mdx b/sources/@repo/docs/content/guides/general-use/config-layers.mdx deleted file mode 100644 index 6edfd38f74..0000000000 --- a/sources/@repo/docs/content/guides/general-use/config-layers.mdx +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Layered configurations -description: Utilize multiple configuration files to manage different environments -sidebar_label: Layered configurations ---- - -## Configuration files - -It is possible to create more than one bud.js configuration file. Each configuration file is applied -in the following order: - -1. `bud.config` - the standard, base configuration. always applied. -2. `bud.config.local` - the local configuration. always applied. -3. `bud.config.${mode}` - the mode-specific configuration. applied if the mode matches. -4. `bud.config.${mode}.local` - the mode-specific local configuration. applied if the mode matches. - -## .env values - -The following `.env` values will be applied to your build automatically, if present: - -- `APP_BASE_PATH` - the base path for your app -- `APP_PUBLIC_PATH` - the public path for your app -- `APP_SRC_PATH` - the `@src` path for your app -- `APP_DIST_PATH` - the `@dist` path for your app -- `APP_STORAGE_PATH` - the `@storage` path for your app -- `APP_MODE` - desired build mode - -## `package.json` values - -You may also use the `bud` key in `package.json` to modify certain base values: - -```json5 title=package.json -{ - "bud": { - "paths": { - "base": string, - "src": string, - "dist": string, - "storage": string - }, - "publicPath": string, - "extensions": { - "allowlist": string[], - "denylist": string[], - "discovery": boolean - } - } -} -``` - -If you are using a multi-instance configuration, you can specify `extensions` to load specific to each instance: - -The top level `extensions` key will be applied to all instances. - -```json5 title=package.json -{ - "bud": { - "extensions": { - "allowlist": string[], - "denylist": string[], - "discovery": boolean - }, - "compiler-a": { - "extensions": { - "allowlist": string[], - "denylist": string[], - "discovery": boolean - } - }, - "compiler-b": { - "extensions": { - "allowlist": string[], - "denylist": string[], - "discovery": boolean - } - } - } -} -``` - -## CLI arguments and flags - -The CLI has many flags for configuring your build. Check the [CLI documentation](/guides/cli) for more information. - -## Order of application - -The following is the order in which bud.js will apply configuration values: - -1. `.env` values -2. `package.json` values -3. all config files -4. CLI arguments and flags - -So, your `bud.config.js` will override any values set in `package.json` or `.env`. Likewise, the CLI arguments will override -any values set in the config. diff --git a/sources/@repo/docs/content/guides/general-use/development-server.mdx b/sources/@repo/docs/content/guides/general-use/development-server.mdx deleted file mode 100644 index 59ac9c926d..0000000000 --- a/sources/@repo/docs/content/guides/general-use/development-server.mdx +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Configuring the dev server -description: Configuring the dev server -slug: dev-server -sidebar_label: Configuring the dev server ---- - -The development server can be configured with [bud.serve](/docs/bud.serve). - -In general it's preferred to use the node `URL` interface to designate the host and port. This is because the `URL` interface is more flexible than a string. - -```js title=bud.config.js -export default async bud => { - bud.serve(new URL(`http://localhost:3000`)) -} -``` - -That said, you can use a `string`: - -```js title=bud.config.js -export default async bud => { - bud.serve(`http://localhost:3000`) -} -``` - -If you only want to change the port, you may use a `number`: - -```js title=bud.config.js -export default async bud => { - bud.serve(3005) -} -``` - -## Using a custom hostname - -Totally supported but it's on you to actually point the hostname. - -## Configuring SSL - -The development server can be [configured to use SSL](/docs/bud.serve#ssl). - -```js title=bud.config.js -export default async bud => { - bud.serve({ - url: new URL(`https://example.test`) - cert: `/path/to/example.test.crt`, - key: `/path/to/example.test.key`, - }) -} -``` - -## Proxying an existing server - -You can use [bud.proxy](/docs/bud.proxy) to proxy an existing server. - -```js title=bud.config.js -export default async bud => { - bud.serve(new URL(`http://localhost:3000`)) - bud.proxy(new URL(`http://example.test`)) -} -``` diff --git a/sources/@repo/docs/content/guides/general-use/managing-dependencies.mdx b/sources/@repo/docs/content/guides/general-use/managing-dependencies.mdx deleted file mode 100644 index cbe038ddbb..0000000000 --- a/sources/@repo/docs/content/guides/general-use/managing-dependencies.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Managing dependencies -description: Managing dependencies -slug: managing-dependencies -sidebar_label: Managing dependencies ---- - -From the yarn docs: - -> If your package is a meta-package of utilities [...], the situation is a bit complicated and you have two different options: -> -> - The preferred one is to list the dependency [...] as both a regular dependency and a peer dependency. Yarn will interpret this pattern as "peer dependency with a default", meaning that your users will be able to take ownership of the Webpack package if they need to, while still giving the package manager the ability to emit a warning if the provided version is incompatible with the one your package expects. -> -> ⸺ [Packages should only ever require what they formally list in their dependencies](https://yarnpkg.com/advanced/rulebook#packages-should-only-ever-require-what-they-formally-list-in-their-dependencies) - -bud.js extensions usually come with everything you need to use a particular tool in your application. But, sometimes your application's needs will be in conflict with the defaults that ship with bud.js. - -A common example of this is Vue 2 vs Vue 3. **@roots/bud-vue** supports Vue 3 by default, but if you need/want to use Vue 2, you can. You'll just need to override some of the peer dependencies in order to do so. - -Likewise, in **@roots/bud-tailwindcss** we will update TailwindCSS when it is safe to do so. If there is a version mismatch between TailwindCSS and something in postcss-preset-env, you'll need to override the version of TailwindCSS in your project in order to use the latest version. Once the conflict is resolved, we'll do the same. - -:::info Be careful - -Once you start overriding dependencies, you're on your own. It's hard enough to manage dependencies in a single project, let alone a monorepo, so our bandwidth to help will be limited. - -::: - -## Overriding peer dependencies - -There isn't an API to manage dependency overrides per se, we just use the peer dependency features built into npm and yarn to make it possible for you to customize your dependencies as needed. To do so you will just install the needed overrides in your project. - -Nearly all of the popular dependencies listed by bud.js and its extensions (vue, react, tailwindcss, typescript, swc, et al) are listed as peer dependencies. Their accepted versions are all very loose. - -## In practice - -A Vue 3 project can just install **@roots/bud** and **@roots/bud-vue** and everything should be perfectly set up. But, at least for now, in order to use Vue 2, you'll need to override: - -- vue (^2.6.14) -- vue-template-compiler (^2.6.14) -- vue-loader (^15.9.4) - -Once installed **@roots/bud-vue** will recognize the version of vue you've installed is for Vue 2 and will configure the project accordingly. - -```ts -class BudVueExtension { - // ... - /** - * Returns true if user has installed a 2.x.x version of vue - */ - @bind - protected async isVue2() { - const manifest = await this.app.module.readManifest(`vue`) - this.logger.log(`vue manifest:`, manifest) - return parseSemver(`vue@${manifest.version}`).version.startsWith(`2`) - } -} -``` diff --git a/sources/@repo/docs/content/guides/general-use/optimizing.mdx b/sources/@repo/docs/content/guides/general-use/optimizing.mdx deleted file mode 100644 index daf55f7d27..0000000000 --- a/sources/@repo/docs/content/guides/general-use/optimizing.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Optimizing -description: Optimizing compiled assets -slug: installation -sidebar_label: Optimizing ---- - -## Minimizing filesize - -Minify css and js output using [bud.minimize](/docs/bud.minimize) - -```js {4} title=bud.config.js -export default async bud => { - bud.minimize() -} -``` - -## Cache busting - -Add filename hashing using [bud.hash](/docs/bud.hash) - -```js {14} title=bud.config.js -export default async bud => bud.hash() -``` - -## Create a runtime - -We can leverage code splitting using [bud.runtime](/docs/bud.runtime) - -```js {15} title=bud.config.js -export default async bud => bud.runtime('single') -``` - -## Split out vendored code - -We'll probably end up with project dependencies. We can use [bud.splitChunks](/docs/bud.splitChunks) to ensure -they are always packaged separately from our application code. - -```js {16} title=bud.config.js -export default async bud => bud.splitChunks() -``` - -## Optimizing images - -Image optimization can be added using the [@roots/bud-imagemin](/extensions/bud-imagemin) extension. - -```npm2yarn -yarn add @roots/bud-imagemin --dev -``` diff --git a/sources/@repo/docs/content/guides/index.mdx b/sources/@repo/docs/content/guides/index.mdx deleted file mode 100644 index a87dbcf886..0000000000 --- a/sources/@repo/docs/content/guides/index.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Getting started -description: How to install and use bud.js -sidebar_label: Getting started -slug: getting-started ---- - -**bud.js** is a web-focused build tool with add-on support for Babel, React, PostCSS, Sass, Typescript, esbuild, ESLint, Prettier, and more. - -## Requirements - -
-
- -
-
- -## Installation - -Add **@roots/bud** as a development dependency using your choice of package manager. - -```bash npm2yarn -npm install @roots/bud --save-dev -``` - -:::info - -If you are using pnpm add `--public-hoist-pattern=*` to the installation command and [use our .pnpmfile.cjs compatibility shim](/guides/general-use/pnpm#pnpmfilecjs-compatibilty-shim). - -::: - -## Usage - -If your project's entrypoint is located at `./src/index.(js|css)` you can now compile it using the [bud build](./cli/build/index.mdx) command. -No configuration is required. The bundled code will be output to `./dist/main.(js|css)`. - -For information on customizing the build for your application see the [configuration basics](configure) guide. - -## Adding features - -**bud.js** is built modularly. This means features can be added as needed by adding extensions to your project. - -The [configuration basics](configure) guide has more information on how to add extensions, but most of them start and end with installing a package. - -For example, you can add swc and postcss support by -installing [@roots/bud-swc](/extensions/bud-swc) and [@roots/bud-postcss](/extensions/bud-postcss/): - -```bash npm2yarn -npm install @roots/bud-swc @roots/bud-postcss --save-dev -``` - -Consult the [extensions directory](/extensions/) for available first-party extensions. - -## Upgrading bud.js - -In general, all dependencies with the `@roots/*` namespace should share the same version. - -To make it easy to keep versions in sync you can use the [bud upgrade](./cli/index.mdx) command. - -```bash npm2yarn -npm run bud upgrade -``` diff --git a/sources/@repo/docs/content/guides/cli/build/development.mdx b/sources/@repo/docs/content/learn/cli/build/development.mdx similarity index 100% rename from sources/@repo/docs/content/guides/cli/build/development.mdx rename to sources/@repo/docs/content/learn/cli/build/development.mdx diff --git a/sources/@repo/docs/content/guides/cli/build/index.mdx b/sources/@repo/docs/content/learn/cli/build/index.mdx similarity index 100% rename from sources/@repo/docs/content/guides/cli/build/index.mdx rename to sources/@repo/docs/content/learn/cli/build/index.mdx diff --git a/sources/@repo/docs/content/guides/cli/build/production.mdx b/sources/@repo/docs/content/learn/cli/build/production.mdx similarity index 100% rename from sources/@repo/docs/content/guides/cli/build/production.mdx rename to sources/@repo/docs/content/learn/cli/build/production.mdx diff --git a/sources/@repo/docs/content/guides/cli/clean.mdx b/sources/@repo/docs/content/learn/cli/clean.mdx similarity index 100% rename from sources/@repo/docs/content/guides/cli/clean.mdx rename to sources/@repo/docs/content/learn/cli/clean.mdx diff --git a/sources/@repo/docs/content/guides/cli/doctor.mdx b/sources/@repo/docs/content/learn/cli/doctor.mdx similarity index 100% rename from sources/@repo/docs/content/guides/cli/doctor.mdx rename to sources/@repo/docs/content/learn/cli/doctor.mdx diff --git a/sources/@repo/docs/content/guides/cli/index.mdx b/sources/@repo/docs/content/learn/cli/index.mdx similarity index 100% rename from sources/@repo/docs/content/guides/cli/index.mdx rename to sources/@repo/docs/content/learn/cli/index.mdx diff --git a/sources/@repo/docs/content/guides/cli/repl.mdx b/sources/@repo/docs/content/learn/cli/repl.mdx similarity index 100% rename from sources/@repo/docs/content/guides/cli/repl.mdx rename to sources/@repo/docs/content/learn/cli/repl.mdx diff --git a/sources/@repo/docs/content/learn/cli/upgrade.mdx b/sources/@repo/docs/content/learn/cli/upgrade.mdx new file mode 100644 index 0000000000..5d561afe46 --- /dev/null +++ b/sources/@repo/docs/content/learn/cli/upgrade.mdx @@ -0,0 +1,10 @@ +--- +title: bud upgrade +description: The `bud upgrade` command +sidebar_label: bud upgrade +--- + +import CodeBlock from '@theme/CodeBlock' +import Output from '!!raw-loader!@site/generated/cli/upgrade.help.md' + +{Output} diff --git a/sources/@repo/docs/content/guides/cli/view.mdx b/sources/@repo/docs/content/learn/cli/view.mdx similarity index 100% rename from sources/@repo/docs/content/guides/cli/view.mdx rename to sources/@repo/docs/content/learn/cli/view.mdx diff --git a/sources/@repo/docs/content/guides/comparison.mdx b/sources/@repo/docs/content/learn/comparison.mdx similarity index 100% rename from sources/@repo/docs/content/guides/comparison.mdx rename to sources/@repo/docs/content/learn/comparison.mdx diff --git a/sources/@repo/docs/content/learn/config/assets.mdx b/sources/@repo/docs/content/learn/config/assets.mdx new file mode 100644 index 0000000000..8440ef9547 --- /dev/null +++ b/sources/@repo/docs/content/learn/config/assets.mdx @@ -0,0 +1,56 @@ +--- +title: Assets +sidebar_label: Assets +--- + +:::info No need to copy imported assets + +If you are already including assets by importing them in a script or stylesheet, you do not need +to copy them explicitly. + +For example, given this stylesheet, copying `@src/fonts/MyFont.woff2` would be unnecessary: + +```js title='index.css' +@font-face { + font-family: 'MyFont'; + src: url(@src/fonts/MyFont.woff2) format('woff2'); +} +``` + +::: + +The [bud.assets](/reference/bud.assets) function is used to copy files to the output directory. + +The simplest way to use it is to pass an array of directories (relative to [your project `@src` directory](#project-paths)) you would like to copy: + +```js title=bud.config.js +export default async bud => { + bud.assets(['images', 'fonts']) +} +``` + +If you want more control over the directory being output to, you can use an array of from/to pairs: + +```js title=bud.config.js +export default async bud => { + bud.assets([ + ['images', 'assets/images'], // from `@src/images` to `@dist/assets/images` + ['fonts', 'assets/fonts'], // from `@src/fonts` to `@dist/assets/fonts` + ]) +} +``` + +For complete control, you can pass an object: + +```js title=bud.config.js +export default async bud => { + bud.assets({ + from: bud.path(`@src`, 'images'), + to: bud.path(`@dist`, 'images', `@name`), // `@name` is the filename (including hash if applicable) + context: bud.path(`@src`), + noErrorOnMissing: true, + toType: `template`, + }) +``` + +You can learn more about this and other details in the [bud.assets documentation](/reference/bud.assets). diff --git a/sources/@repo/docs/content/learn/config/entrypoints.mdx b/sources/@repo/docs/content/learn/config/entrypoints.mdx new file mode 100644 index 0000000000..fb9d93a3c9 --- /dev/null +++ b/sources/@repo/docs/content/learn/config/entrypoints.mdx @@ -0,0 +1,47 @@ +--- +title: Entrypoints +sidebar_label: Entrypoints +--- + +bud.js uses the concept of "entrypoints" to group application scripts and styles. Entrypoints are defined using [bud.entry](/reference/bud.entry). + +You can think of an entrypoint as a "page" in your application. Each entrypoint will have its own output file. + +:::info + +If your application's entrypoint is located at `@src/index.js` then you don't need to do anything. bud.js will automatically +detect this and create an entrypoint for you. + +::: + +If you only have a single entrypoint then it is enough to just pass the filename: + +```js title=bud.config.js +export default async bud => { + bud.entry('app') // src/app.js +} +``` + +If you have more than one file to include in the bundle, you can use an array: + +```js title=bud.config.js +export default async bud => { + bud.entry(['app.js', 'global.css']) +} +``` + +If you have additional entrypoints you may call [bud.entry](/reference/bud.entry) multiple times. + +But, it might be preferable to use an object: + +```js title=bud.config.js +export default async bud => { + bud.entry({ + app: ['app.js', 'global.css'], + landing: ['landing.js', 'landing.css'], + }) +} +``` + +There is still more that this function can do, but for our overview this is more than enough. You can learn more about this and +other details in the [bud.entry documentation](/reference/bud.entry). diff --git a/sources/@repo/docs/content/guides/general-use/alternative-config-syntax.mdx b/sources/@repo/docs/content/learn/config/files/bud.config.mdx similarity index 52% rename from sources/@repo/docs/content/guides/general-use/alternative-config-syntax.mdx rename to sources/@repo/docs/content/learn/config/files/bud.config.mdx index d912d6849b..075f652759 100644 --- a/sources/@repo/docs/content/guides/general-use/alternative-config-syntax.mdx +++ b/sources/@repo/docs/content/learn/config/files/bud.config.mdx @@ -1,43 +1,103 @@ --- -title: Alternative config syntaxes -description: Configure bud.js with typescript, yml or json -sidebar_label: Alternative config syntaxes +title: bud.config +sidebar_label: bud.config.ts +description: Used to configure bud.js --- import Tabs from '@theme/Tabs' import TabItem from '@theme/TabItem' -import CodeBlock from '@theme/CodeBlock' -import YML from '!!raw-loader!@site/../../../examples/config-yml/bud.config.yml' -In addition to `.js`, `.cjs` and `.mjs` configurations, **bud.js** supports configuration files authored with TypeScript, [json5](https://json5.org/) and yml. +bud.js config files are the most straight forward way of interfacing with bud.js. -## TypeScript +- The file name should include `bud` in the name. +- The module should be located in the project root or the `./config` directory. +- The module can be written in JavaScript, TypeScript, YML or JSON5. +- JavaScript and TypeScript configurations can either export a configuration function or import bud and use it directly. -You can use TypeScript to configure your build regardless of if you are using TypeScript in your project. The config file is not typechecked. +:::info esbuild-wasm -You can import the `Bud` types from `@roots/bud`. +By default bud.js uses [esbuild-wasm](https://www.npmjs.com/package/esbuild-wasm) to transpile the config file when authored with TypeScript. + +If you prefer you can install [esbuild](https://www.npmjs.com/package/esbuild) and it will be preferred. + +The esbuild team advises that using esbuild is faster than esbuild-wasm, but the benefit of esbuild-wasm is that it doesn't need to be built during installation. + +::: -```ts +## Example configurations + + + + +```js title=bud.config.ts import type {Bud} from '@roots/bud' export default async (bud: Bud) => { - // configure bud + bud.entry(`app`, [`app.js`, `app.css`]) } ``` -By default bud.js uses [esbuild-wasm](https://www.npmjs.com/package/esbuild-wasm) to transpile the config file when authored with TypeScript. + + + + +```js title=bud.config.js +/** @param {import('@roots/bud').Bud} bud */ +export default async bud => { + bud.entry(`app`, [`app.js`, `app.css`]) +} +``` + + + + + +```yml title=bud.config.yml +entry: ['app', ['app.js', 'app.css']] +``` + + + + + +```json title=bud.config.json +{ + "entry": ["app", ["app.js", "app.css"]] +} +``` + + + + +## Importing bud directly + +As mentioned above, you can also elect to import bud directly and use it in your configuration. + +```ts title=bud.config.ts +import {bud} from '@roots/bud' + +bud.entry(`app`, [`app.js`, `app.css`]) +``` + +## Using multiple configuration files + +It is possible to create more than one bud.js configuration file. + +When more than one configuration file is present they are execuetd in the following order: -If you prefer you can install [esbuild](https://www.npmjs.com/package/esbuild) and it will be used instead automatically. +1. `bud.*` - the standard, base configuration. +2. `bud.local.*` - local configuration. +3. `bud.{production,development}.*` - mode specific configuration. Applied when `bud.mode` matches. +4. `bud.{production,development}.local.*` - mode specific local configuration. Applied when `bud.mode` matches. -The esbuild team advises that using esbuild is faster than esbuild-wasm, but the benefit of esbuild-wasm is that it doesn't need to be compiled during installation. -Additionally, results of the transform are cached, so either way the transformer is only invoked a single time. -In our testing the extra installation time outweighs the performance gains. +You may want to add `bud.local.*` to your `.gitignore` file. This way contributors to your project can make specific overrides using `bud.local.*` files +without affecting the base configuration kept in source control. -## YML +## Configuring bud.js with YML Each key is a reference to a `Bud` call. The supplied values are the arguments to that call. -For instance, the equivalent of the following call to [bud.entry](/docs/bud.entry): +For instance, the equivalent of the following call to [bud.entry](/reference/bud.entry): ```js bud.entry('app', 'app.js') @@ -108,7 +168,7 @@ webpackConfig: > => config => ({...config, parallelism: 1}) ``` -[bud.tap](/docs/bud.tap) and [bud.tapAsync](/docs/bud.tapAsync) can be helpful for dynamic configuration and work like this: +[bud.tap](/reference/bud.tap) and [bud.tapAsync](/reference/bud.tapAsync) can be helpful for dynamic configuration and work like this: ```yml tap: > @@ -127,9 +187,9 @@ tapAsync: > If you're doing a lot of this remember that you can create JS configurations in addition to the yml one. -## JSON +## Configuring bud.js with JSON -JSON works by the same rules as yml and you can use json5 syntax (comments, non-quoted keys). +JSON uses the same rules as yml. You can use JSON5 syntax (comments, non-quoted keys) similar to what is supported in `tsconfig.json`. ```json { diff --git a/sources/@repo/docs/content/learn/config/files/env.mdx b/sources/@repo/docs/content/learn/config/files/env.mdx new file mode 100644 index 0000000000..835c106741 --- /dev/null +++ b/sources/@repo/docs/content/learn/config/files/env.mdx @@ -0,0 +1,6 @@ +--- +title: .env +sidebar_label: .env +--- + +You can access environment variables set in a `.env` file in your project root using [bud.env](/reference/bud.env). diff --git a/sources/@repo/docs/content/learn/config/files/package.mdx b/sources/@repo/docs/content/learn/config/files/package.mdx new file mode 100644 index 0000000000..41e73394a6 --- /dev/null +++ b/sources/@repo/docs/content/learn/config/files/package.mdx @@ -0,0 +1,118 @@ +--- +title: package.json +sidebar_label: package.json +--- + +Your project `package.json` has bud.js specific fields that can be used to configure your project. + +## JSON schema + +To make sure your `package.json` is valid, you can add the bud.js schema to your `package.json`: `https://bud.js.org/bud.package.json`. This is totally optional. + +```json title=package.json +{ + "name": "my-project", + "$schema": "https://bud.js.org/bud.package.json", + "devDependencies": { + "@roots/bud": "latest" + } +} +``` + +## bud.js fields + +bud.js specific fields are added to the top-level `bud` key in your `package.json`. + +### bud.extensions.discover + +Disable extension autoload by setting `bud.extensions.discover` to `false`. + +```json title=package.json +{ + "name": "my-project", + "$schema": "https://bud.js.org/bud.package.json", + "bud": { + "extensions": { + "discover": false + } + }, + "devDependencies": { + "@roots/bud": "latest" + } +} +``` + +### bud.extensions.allowlist + +Allow only specified extensions to autoload by setting `bud.extensions.allowlist`. + +```json title=package.json +{ + "name": "my-project", + "$schema": "https://bud.js.org/bud.package.json", + "bud": { + "extensions": { + "allowlist": ["@roots/bud-babel"] + } + }, + "devDependencies": { + "@roots/bud": "latest", + "@roots/bud-babel": "latest", + "@roots/bud-postcss": "latest" + } +} +``` + +### bud.extensions.denylist + +Prevent particular extensions from autoloading by setting `bud.extensions.denylist`. + +```json title=package.json +{ + "name": "my-project", + "$schema": "https://bud.js.org/bud.package.json", + "bud": { + "extensions": { + "denylist": ["@roots/bud-postcss"] + } + }, + "devDependencies": { + "@roots/bud": "latest", + "@roots/bud-babel": "latest", + "@roots/bud-postcss": "latest" + } +} +``` + +## Multi-instance configurations + +If you are using bud.js in a multi-instance configuration, you can key the options by the instance names. + +Any top-level options will be applied to all instances, with instance-specific options taking precedence. + +```json title=package.json +{ + "name": "my-project", + "$schema": "https://bud.js.org/bud.package.json", + "bud": { + "extensions": { + "discover": false + }, + "instance-a": { + "extensions": { + "allowlist": ["@roots/bud-swc"] + } + }, + "instance-b": { + "extensions": { + "allowlist": ["@roots/bud-babel"] + } + } + }, + "devDependencies": { + "@roots/bud": "latest", + "@roots/bud-babel": "latest", + "@roots/bud-swc": "latest" + } +} +``` diff --git a/sources/@repo/docs/content/learn/config/files/tsconfig.mdx b/sources/@repo/docs/content/learn/config/files/tsconfig.mdx new file mode 100644 index 0000000000..f944c1a29a --- /dev/null +++ b/sources/@repo/docs/content/learn/config/files/tsconfig.mdx @@ -0,0 +1,56 @@ +--- +title: tsconfig.json +sidebar_label: tsconfig.json +--- + +You can enhance your developer experience in vscode and other editors by creating a `tsconfig.json` file. + +There are base configs provided by **@roots/bud** for you to extend: + +- [@roots/bud/config/jsconfig.json](https://github.com/roots/bud/tree/main/sources/@roots/bud/config/jsconfig.json) +- [@roots/bud/config/tsconfig.json](https://github.com/roots/bud/tree/main/sources/@roots/bud/config/tsconfig.json) + +### Example tsconfig.json + +```json title=tsconfig.json +{ + "extends": "@roots/bud/config/tsconfig.json", + "compilerOptions": { + "baseUrl": "./src", + "outDir": "./dist", + "paths": { + "@src/*": ["./src/*"] + }, + "types": [ + "node", + "webpack/module", + "@roots/bud", + "@roots/bud-postcss", + "@roots/bud-react", + "@roots/bud-swc", + "@roots/bud-tailwindcss" + ] + }, + "files": ["bud.config.ts"], + "include": ["src"], + "exclude": ["node_modules", "dist"], + "bud": { + "useCompilerOptions": false + } +} +``` + +### Tips + +- Add any bud extensions you are using to `compilerOptions.types` so that you're IDE can will pick up on the types. We also recommend adding `node` and `webpack/module` to this array. +- Add any [aliases](/reference/bud.alias) you are using to `compilerOptions.paths` so that your IDE can resolve them. +- Make sure `bud.config.js` is included in the `include` array so that your IDE will apply discovered types to the config file. + +### bud.useCompilerOptions + +If you enable `bud.useCompilerOptions` in your `tsconfig.json` file then **@roots/bud** will apply certain options from `compilerOptions` to the bud config. + +- `compilerOptions.baseUrl` will set the `@src` path. +- `compilerOptions.outDir` will set the `@dist` path. +- `compilerOptions.paths` will create bud paths and aliases. +- `include` will call `bud.compilePaths` on the supplied values. diff --git a/sources/@repo/docs/content/learn/config/optimization.mdx b/sources/@repo/docs/content/learn/config/optimization.mdx new file mode 100644 index 0000000000..ba68e7aac4 --- /dev/null +++ b/sources/@repo/docs/content/learn/config/optimization.mdx @@ -0,0 +1,53 @@ +--- +title: Optimization +sidebar_label: Optimization +--- + +## File hashing + +Use the [bud.hash](/reference/bud.hash) function to generate a hash for each file in the bundle. This hash will be added to outputted files. + +```js title=bud.config.js +export default async bud => { + bud.hash() +} +``` + +## Minimizing code + +Use the [bud.minimize](/reference/bud.minimize) function to run your application code through a minifier. + +```js title=bud.config.js +export default async bud => { + bud.minimize() +} +``` + +## Creating a runtime + +You may create an application runtime using [bud.runtime](/reference/bud.runtime). Using the `single` option is probably +the simplest and best solution for most applications: + +```js title=bud.config.js +export default async bud => { + bud.runtime('single') +} +``` + +## Creating a vendor chunk + +You can perform general code splitting with [bud.splitChunks](/reference/bud.splitChunks). + +```js title=bud.config.js +export default async bud => { + bud.splitChunks() +} +``` + +## Optimizing images + +You can optimize images using the [@roots/bud-imagemin extension](/extensions/bud-imagemin). + +```sh npm2yarn +npm install @roots/bud-imagemin --save-dev +``` diff --git a/sources/@repo/docs/content/learn/config/paths.mdx b/sources/@repo/docs/content/learn/config/paths.mdx new file mode 100644 index 0000000000..7dec4761d5 --- /dev/null +++ b/sources/@repo/docs/content/learn/config/paths.mdx @@ -0,0 +1,50 @@ +--- +title: Paths +sidebar_label: Paths +--- + +## Setting application paths + +[bud.setPath](/reference/bud.setPath) is used to set project source and output paths. + +```js title=bud.config.js +export default async bud => { + /* Set the source path.*/ + bud.setPath('@src', 'source') + /* Set the output path.*/ + bud.setPath('@dist', 'build') +} +``` + +The `@src` and `@dist` handles are special handles associated with the input and output base directories. + +## Referencing application paths + +Once set, paths can be referenced using [bud.path](/reference/bud.path). + +```js title=bud.config.js +export default async bud => { + bud.path('@src') // absolute path to source directory + bud.path('@dist') // absolute path to output directory +} +``` + +## Globbing + +[bud.glob](/reference/bud.glob) can be used to construct a list of files matching a given pattern. + +This function is asychronous. + +```js title=bud.config.js +export default async bud => { + await bud.glob('@src', '**/*.js') // returns an array of absolute paths +} +``` + +There is a synchronous version available as well: [bud.globSync](/reference/bud.globSync). + +```js title=bud.config.js +export default async bud => { + bud.globSync('@src', '**/*.js') // returns an array of absolute paths +} +``` diff --git a/sources/@repo/docs/content/learn/config/server.mdx b/sources/@repo/docs/content/learn/config/server.mdx new file mode 100644 index 0000000000..9f3f392d77 --- /dev/null +++ b/sources/@repo/docs/content/learn/config/server.mdx @@ -0,0 +1,58 @@ +--- +title: Development server +description: Development server +slug: dev-server +sidebar_label: Development server +--- + +## Setting the dev URL + +Use [bud.setUrl](/reference/bud.setUrl) to set the development server URL. + +```js title=bud.config.js +export default async bud => { + bud.setUrl(3030) // Deltron zero hero not no small feat +} +``` + +## Setting the proxy URL + +Use [bud.setProxyUrl](/reference/bud.setProxyUrl) to set the development server proxy URL. + +```js title=bud.config.js +export default async bud => { + bud.setProxyUrl(`http://example.test`) +} +``` + +## Setting public URLs + +You can use [bud.setPublicUrl](/reference/bud.setPublicUrl) and [bud.setPublicProxyUrl](/reference/bud.setPublicProxyUrl) to set the public URL of the development server. + +This is useful in containerized development environments like Docker where the internal URL is different from the external URL. + +Here is an example of what this might look like, but it is going to depend heavily on your setup: + +```js title=bud.config.js +bud + .setUrl(3000) + .setPublicUrl(`http://example.test:3000`) + .setProxyUrl(8080) + .setPublicProxyUrl(`http://example.test`) +``` + +## Advanced configuration + +The development server can be configured with [bud.serve](/reference/bud.serve). This is primarily used to handle +configuring bud.js to use an [SSL certificate](/reference/bud.serve#ssl), but it exposes all node options so the possibilities +are really only limited by the runtime. + +```js title=bud.config.js +export default async bud => { + bud.serve({ + url: new URL(`https://example.test`) + cert: `/path/to/example.test.crt`, + key: `/path/to/example.test.key`, + }) +} +``` diff --git a/sources/@repo/docs/content/guides/extending/decorators.mdx b/sources/@repo/docs/content/learn/extending/decorators.mdx similarity index 100% rename from sources/@repo/docs/content/guides/extending/decorators.mdx rename to sources/@repo/docs/content/learn/extending/decorators.mdx diff --git a/sources/@repo/docs/content/guides/extending/index.mdx b/sources/@repo/docs/content/learn/extending/index.mdx similarity index 96% rename from sources/@repo/docs/content/guides/extending/index.mdx rename to sources/@repo/docs/content/learn/extending/index.mdx index d6fd819034..9f77c28f55 100644 --- a/sources/@repo/docs/content/guides/extending/index.mdx +++ b/sources/@repo/docs/content/learn/extending/index.mdx @@ -4,7 +4,7 @@ description: Overview of instantiating bud.js directly from Node sidebar_label: Extending --- -You can add additional functionality to **bud.js** using the extensions API. +You can add additional functionality to **bud.js** by writing a bud.js extension. ## Extension shape @@ -44,12 +44,9 @@ export default class MyExtension extends Extension { } ``` -A `label` is not strictly required but extensions without a `label` will have a unique id generated for them. Because this id is generated there is no -straight forward way to reference the extension from the outside. - ### dependsOn -Extensions may depend on other other extensions. For instance, if you are authoring an extension that manages postcss plugins then your extension +Extensions may depend on other other extensions. For instance, if you are authoring an extension that manages PostCSS plugins then your extension depends on the presence of `@roots/bud-postcss`. To ensure dependencies are available, you may list their `label`s in a `dependsOn` public property. The `dependsOn` property is expressed as a `Set`: diff --git a/sources/@repo/docs/content/guides/extending/lifecycle.mdx b/sources/@repo/docs/content/learn/extending/lifecycle.mdx similarity index 100% rename from sources/@repo/docs/content/guides/extending/lifecycle.mdx rename to sources/@repo/docs/content/learn/extending/lifecycle.mdx diff --git a/sources/@repo/docs/content/guides/extending/packaging.mdx b/sources/@repo/docs/content/learn/extending/packaging.mdx similarity index 100% rename from sources/@repo/docs/content/guides/extending/packaging.mdx rename to sources/@repo/docs/content/learn/extending/packaging.mdx diff --git a/sources/@repo/docs/content/guides/general-use/compiler-sources.mdx b/sources/@repo/docs/content/learn/general-use/compiler-sources.mdx similarity index 95% rename from sources/@repo/docs/content/guides/general-use/compiler-sources.mdx rename to sources/@repo/docs/content/learn/general-use/compiler-sources.mdx index ede4df550a..c72b3dafc7 100644 --- a/sources/@repo/docs/content/guides/general-use/compiler-sources.mdx +++ b/sources/@repo/docs/content/learn/general-use/compiler-sources.mdx @@ -6,7 +6,7 @@ sidebar_label: Adding compiler sources sidebar_position: 5 --- -By default, **bud.js** only resolves source code from [the `@src` directory](/docs/bud.path). +By default, **bud.js** only resolves source code from [the `@src` directory](/reference/bud.path). Nearly all of the modules you install will have been compiled before they are published. It's almost always a waste to run this code through Babel or whatever other compiler you may be using. @@ -23,7 +23,7 @@ Common examples: :::info bud.compilePaths -There is a function to simplify this available in bud@6.9.0: [bud.compilePaths](/docs/bud.compilePaths). +There is a function to simplify this available in bud@6.9.0: [bud.compilePaths](/reference/bud.compilePaths). ::: diff --git a/sources/@repo/docs/content/guides/general-use/customizing-loaders.mdx b/sources/@repo/docs/content/learn/general-use/customizing-loaders.mdx similarity index 100% rename from sources/@repo/docs/content/guides/general-use/customizing-loaders.mdx rename to sources/@repo/docs/content/learn/general-use/customizing-loaders.mdx diff --git a/sources/@repo/docs/content/guides/general-use/esmodules.mdx b/sources/@repo/docs/content/learn/general-use/esmodules.mdx similarity index 100% rename from sources/@repo/docs/content/guides/general-use/esmodules.mdx rename to sources/@repo/docs/content/learn/general-use/esmodules.mdx diff --git a/sources/@repo/docs/content/guides/general-use/extensions.mdx b/sources/@repo/docs/content/learn/general-use/extensions.mdx similarity index 84% rename from sources/@repo/docs/content/guides/general-use/extensions.mdx rename to sources/@repo/docs/content/learn/general-use/extensions.mdx index cd056d401d..f663bdbb1d 100644 --- a/sources/@repo/docs/content/guides/general-use/extensions.mdx +++ b/sources/@repo/docs/content/learn/general-use/extensions.mdx @@ -7,7 +7,7 @@ sidebar_label: Extensions ## Register an extension -Extensions included in `package.json` are automatically instantiated. You can also add extensions using [bud.use](/docs/bud.use). +Extensions included in `package.json` are automatically instantiated. You can also add extensions using [bud.use](/reference/bud.use). However, you can choose to use the bud.js extensions API directly. @@ -127,17 +127,17 @@ bud.extensions ## Built-in extensions -| label | description | exposed | -| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------- | -| @roots/bud-extensions/cdn | Adds remote import functionality | bud.cdn | -| @roots/bud-extensions/esm | Adds ESM support functionality | bud.esm | -| @roots/bud-extensions/clean-webpack-plugin | Cleans output directory on build | | -| @roots/bud-extensions/copy-webpack-plugin | Copies assets (used by [bud.assets](/docs/bud.assets)) | | -| @roots/bud-extensions/fix-style-only-entrypoints | Removes JS output from entrypoints which only contain CSS | | -| @roots/bud-extensions/html-webpack-plugin | HTML functionality (used by [bud.html](/docs/bud.html)) | | -| @roots/bud-extensions/interpolate-html-webpack-plugin | Adds `create-react-app`-like template variable support for HTML files | | -| @roots/bud-extensions/mini-css-extract-plugin | Optimized CSS loading | | -| @roots/bud-extensions/webpack-define-plugin | Defines variables which can be used in the application (used by [bud.define](/docs/bud.define)) | | -| @roots/bud-extensions/webpack-hot-module-replacement-plugin | Adds HMR support | | -| @roots/bud-extensions/webpack-manifest-plugin | Emits `manifest.json` | | -| @roots/bud-extensions/webpack-provide-plugin | Provides import(s) globally to the application | | +| label | description | exposed | +| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------- | +| @roots/bud-extensions/cdn | Adds remote import functionality | bud.cdn | +| @roots/bud-extensions/esm | Adds ESM support functionality | bud.esm | +| @roots/bud-extensions/clean-webpack-plugin | Cleans output directory on build | | +| @roots/bud-extensions/copy-webpack-plugin | Copies assets (used by [bud.assets](/reference/bud.assets)) | | +| @roots/bud-extensions/fix-style-only-entrypoints | Removes JS output from entrypoints which only contain CSS | | +| @roots/bud-extensions/html-webpack-plugin | HTML functionality (used by [bud.html](/reference/bud.html)) | | +| @roots/bud-extensions/interpolate-html-webpack-plugin | Adds `create-react-app`-like template variable support for HTML files | | +| @roots/bud-extensions/mini-css-extract-plugin | Optimized CSS loading | | +| @roots/bud-extensions/webpack-define-plugin | Defines variables which can be used in the application (used by [bud.define](/reference/bud.define)) | | +| @roots/bud-extensions/webpack-hot-module-replacement-plugin | Adds HMR support | | +| @roots/bud-extensions/webpack-manifest-plugin | Emits `manifest.json` | | +| @roots/bud-extensions/webpack-provide-plugin | Provides import(s) globally to the application | | diff --git a/sources/@repo/docs/content/learn/general-use/managing-dependencies.mdx b/sources/@repo/docs/content/learn/general-use/managing-dependencies.mdx new file mode 100644 index 0000000000..fa75debee5 --- /dev/null +++ b/sources/@repo/docs/content/learn/general-use/managing-dependencies.mdx @@ -0,0 +1,30 @@ +--- +title: Managing dependencies +description: Managing dependencies +slug: managing-dependencies +sidebar_label: Managing dependencies +--- + +bud.js extensions usually come with everything you need to use a particular tool in your application. But, sometimes your application's needs will be in conflict with the defaults that ship with bud.js. + +A common example of this is Vue 2 vs Vue 3. **@roots/bud-vue** supports Vue 3 by default, but if you need/want to use Vue 2, you can. You'll just need to override some of the peer dependencies in order to do so. + +:::info Be careful + +Once you start overriding dependencies, you're on your own. It's hard enough to manage dependencies in a single project, let alone a monorepo, so our bandwidth to help will be limited. + +::: + +## Overriding peer dependencies + +There isn't an API to manage dependency overrides per se, we just use the module resolution features built into npm and yarn to make it possible for you to customize your dependencies as needed. To do so you will just install the needed overrides in your project. + +## Example: Using Vue 2 instead of Vue 3 + +A Vue 3 project can just install **@roots/bud** and **@roots/bud-vue** and everything should be perfectly set up. But, at least for now, in order to use Vue 2, you'll need to override the peer dependencies that **@roots/bud-vue** ships with: + +- vue (2.6.14) +- vue-template-compiler (2.6.14) +- vue-loader (15.9.4) + +Installation diff --git a/sources/@repo/docs/content/guides/general-use/multi-instance.mdx b/sources/@repo/docs/content/learn/general-use/multi-instance.mdx similarity index 90% rename from sources/@repo/docs/content/guides/general-use/multi-instance.mdx rename to sources/@repo/docs/content/learn/general-use/multi-instance.mdx index 543c2c5cdc..f9838aacdb 100644 --- a/sources/@repo/docs/content/guides/general-use/multi-instance.mdx +++ b/sources/@repo/docs/content/learn/general-use/multi-instance.mdx @@ -17,7 +17,7 @@ different build requirements for different application components — it is ## Creating child instances -To create a new child instance, we can use [bud.make](/docs/bud.make). +To create a new child instance, we can use [bud.make](/reference/bud.make). The simplest implementation sets the `label` of the compiler with a `string`, and provides a configuration callback: @@ -38,14 +38,14 @@ export default async bud => { } ``` -See the [bud.make](/docs/bud.make) documentation for more information. +See the [bud.make](/reference/bud.make) documentation for more information. ## Using the `--target` flag The other benefit is a potentially massive workflow improvement. Let's say that we have to work on the `theme` more often than the `plugin`. With the above config we don't have to rebuild the `plugin` code again just to work on our `theme` code. -We can use the `bud` cli to only run the compiler we need using [the `--target` flag](/guides/cli/build). +We can use the `bud` cli to only run the compiler we need using [the `--target` flag](/learn/cli/build). ```sh $ yarn bud build --target theme @@ -62,7 +62,7 @@ $ yarn bud build --target theme --target plugin By default, all extensions will be applied to all compilers in the project. If the extensions differ between compilers you can either use the `--no-discovery` flag or set the -[`bud.extensions.discovery` property in your root package.json to `false`](/guides/general-use/config-layers) +[`bud.extensions.discovery` property in your root package.json to `false`](/learn/config/files/package) to prevent extensions from being automatically injected. Then, you can manually load the extensions on a per-compiler basis: @@ -91,9 +91,9 @@ Any configuration of the development server should be done in the parent context This includes: -- [bud.serve](/docs/bud.serve) -- [bud.proxy](/docs/bud.proxy) -- [bud.watch](/docs/bud.watch) +- [bud.serve](/reference/bud.serve) +- [bud.proxy](/reference/bud.proxy) +- [bud.watch](/reference/bud.watch) ```ts title=bud.config.js export default async bud => { diff --git a/sources/@repo/docs/content/guides/general-use/node-api.mdx b/sources/@repo/docs/content/learn/general-use/node-api.mdx similarity index 72% rename from sources/@repo/docs/content/guides/general-use/node-api.mdx rename to sources/@repo/docs/content/learn/general-use/node-api.mdx index 6c5948a21a..552d56184c 100644 --- a/sources/@repo/docs/content/guides/general-use/node-api.mdx +++ b/sources/@repo/docs/content/learn/general-use/node-api.mdx @@ -9,7 +9,7 @@ import Code from '@theme/CodeBlock' :::note Work-in-progress -These docs are incomplete. Check out the [examples directory](https://github.com/roots/bud/tree/main/examples) in the **bud.js** repo for living examples. +This is a work-in-progress. ::: diff --git a/sources/@repo/docs/content/guides/general-use/pnpm.mdx b/sources/@repo/docs/content/learn/general-use/pnpm.mdx similarity index 100% rename from sources/@repo/docs/content/guides/general-use/pnpm.mdx rename to sources/@repo/docs/content/learn/general-use/pnpm.mdx diff --git a/sources/@repo/docs/content/guides/general-use/remote-sources.mdx b/sources/@repo/docs/content/learn/general-use/remote-sources.mdx similarity index 100% rename from sources/@repo/docs/content/guides/general-use/remote-sources.mdx rename to sources/@repo/docs/content/learn/general-use/remote-sources.mdx diff --git a/sources/@repo/docs/content/learn/getting-started/adding-emotion.mdx b/sources/@repo/docs/content/learn/getting-started/adding-emotion.mdx new file mode 100644 index 0000000000..3a06e13908 --- /dev/null +++ b/sources/@repo/docs/content/learn/getting-started/adding-emotion.mdx @@ -0,0 +1,30 @@ +--- +title: Adding Emotion +description: How to get started with Emotion +sidebar_label: Adding Emotion +--- + +## Installing bud.js dependencies + +To get started with Emotion, install the [@roots/bud-emotion](/extensions/bud-emotion) extension to your project along with a compatible compiler: + +- [@roots/bud-babel](/extensions/bud-babel) +- [@roots/bud-swc](/extensions/bud-swc) + +We recommend using [@roots/bud-swc](/extensions/bud-swc): + +```bash npm2yarn +npm install @roots/bud-swc @roots/bud-emotion --save-dev +``` + +## Installing production dependencies + +Emotion requires the several packages to be installed in your project. + +We will try and resolve them for you but it is a good idea to install them as explicit dependencies: + +```bash npm2yarn +npm install @emotion/css @emotion/react @emotion/styled --save +``` + +See the [Emotion documentation](https://emotion.sh/docs/install) for more information. diff --git a/sources/@repo/docs/content/learn/getting-started/adding-eslint.mdx b/sources/@repo/docs/content/learn/getting-started/adding-eslint.mdx new file mode 100644 index 0000000000..1cf41fad4d --- /dev/null +++ b/sources/@repo/docs/content/learn/getting-started/adding-eslint.mdx @@ -0,0 +1,25 @@ +--- +title: Adding Eslint +description: How to get started with Eslint +sidebar_label: Adding Eslint +--- + +## Installing bud.js dependencies + +To get started with Eslint, install the [@roots/bud-eslint](/extensions/bud-eslint) extension to your project. + +```bash npm2yarn +npm install @roots/bud-eslint --save-dev +``` + +If you want to extend one of our first party configurations, you'll also want to install `@roots/eslint-config`: + +```bash npm2yarn +npm install @roots/eslint-config --save-dev +``` + +## Configuring eslint + +Once you've installed the extension you can configure it either in your [bud.config file](/learn/config/files/bud.config) or in a separate `.eslintrc.js` file. + +For more information on configuring eslint refer to the [@roots/bud-eslint documentation](/extensions/bud-eslint). diff --git a/sources/@repo/docs/content/learn/getting-started/adding-postcss.mdx b/sources/@repo/docs/content/learn/getting-started/adding-postcss.mdx new file mode 100644 index 0000000000..ccc7c7258b --- /dev/null +++ b/sources/@repo/docs/content/learn/getting-started/adding-postcss.mdx @@ -0,0 +1,17 @@ +--- +title: Adding PostCSS +description: How to get started with PostCSS +sidebar_label: Adding PostCSS +--- + +## Installing bud.js dependencies + +To get started with PostCSS, install the [@roots/bud-postcss](/extensions/bud-postcss) extension. + +```sh npm2yarn +npm install @roots/bud-swc --save-dev +``` + +## Configuration + +No configuration is required. If you need to further customize PostCSS for your application, reference the [@roots/bud-postcss documentation](/extensions/bud-postcss). diff --git a/sources/@repo/docs/content/learn/getting-started/adding-react.mdx b/sources/@repo/docs/content/learn/getting-started/adding-react.mdx new file mode 100644 index 0000000000..5be81e082c --- /dev/null +++ b/sources/@repo/docs/content/learn/getting-started/adding-react.mdx @@ -0,0 +1,36 @@ +--- +title: Adding React +description: How to get started with React +sidebar_label: Adding React +--- + +## Installing bud.js dependencies + +To get started with React, install the [@roots/bud-react](/extensions/bud-react) extension to your project along with a compatible compiler: + +- [@roots/bud-babel](/extensions/bud-babel) +- [@roots/bud-esbuild](/extensions/bud-esbuild) +- [@roots/bud-swc](/extensions/bud-swc) +- [@roots/bud-typescript](/extensions/bud-typescript) + +We recommend using [@roots/bud-swc](/extensions/bud-swc): + +```bash npm2yarn +npm install @roots/bud-swc @roots/bud-typescript --save-dev +``` + +If you need to further customize React for your application, reference the [@roots/bud-react documentation](/extensions/bud-react). + +## Installing production dependencies + +React requires installing `react` and `react-dom` as production dependencies. + +We will try and resolve them for you but it is a good idea to install them as explicit dependencies: + +```bash npm2yarn +npm install react react-dom --save +``` + +## Configuration + +No configuration is required. If you need to customize the provided defaults refer to the [@roots/bud-react documentation](/extensions/bud-react). diff --git a/sources/@repo/docs/content/learn/getting-started/adding-sass.mdx b/sources/@repo/docs/content/learn/getting-started/adding-sass.mdx new file mode 100644 index 0000000000..1c7fb19b2c --- /dev/null +++ b/sources/@repo/docs/content/learn/getting-started/adding-sass.mdx @@ -0,0 +1,15 @@ +--- +title: Adding Sass +description: How to get started with Sass +sidebar_label: Adding Sass +--- + +## Installing bud.js dependencies + +To get started with Sass, install the [@roots/bud-sass](/extensions/bud-sass) extension. + +```sh npm2yarn +npm install @roots/bud-swc --save-dev +``` + +If you need to further customize Sass for your application, reference the [@roots/bud-sass documentation](/extensions/bud-sass). diff --git a/sources/@repo/docs/content/learn/getting-started/adding-stylelint.mdx b/sources/@repo/docs/content/learn/getting-started/adding-stylelint.mdx new file mode 100644 index 0000000000..d33d7ec82e --- /dev/null +++ b/sources/@repo/docs/content/learn/getting-started/adding-stylelint.mdx @@ -0,0 +1,19 @@ +--- +title: Adding Stylelint +description: How to get started with Stylelint +sidebar_label: Adding Stylelint +--- + +## Installing bud.js dependencies + +To get started with Stylelint, install the [@roots/bud-stylelint](/extensions/bud-stylelint) extension to your project. + +```bash npm2yarn +npm install @roots/bud-stylelint --save-dev +``` + +## Configuring stylelint + +Once you've installed the extension you can configure it either in your bud.config file or in a separate .stylelintrc.js file. + +For more information on configuring stylelint refer to the [@roots/bud-stylelint documentation](/extensions/bud-stylelint). diff --git a/sources/@repo/docs/content/learn/getting-started/adding-tailwindcss.mdx b/sources/@repo/docs/content/learn/getting-started/adding-tailwindcss.mdx new file mode 100644 index 0000000000..06696c5402 --- /dev/null +++ b/sources/@repo/docs/content/learn/getting-started/adding-tailwindcss.mdx @@ -0,0 +1,21 @@ +--- +title: Adding TailwindCSS +description: How to get started with TailwindCSS +sidebar_label: Adding TailwindCSS +--- + +## Installing bud.js dependencies + +To get started with TailwindCSS, install the [@roots/bud-tailwindcss](/extensions/bud-tailwindcss) extension to your project along with [@roots/bud-postcss](/extensions/bud-postcss). + +```sh npm2yarn +npm install @roots/bud-postcss @roots/bud-tailwindcss --save-dev +``` + +## Configuration + +No configuration is required. If you need to customize your TailwindCSS configuration, you can do so by creating a `tailwind.config.js` file in your project. + +Refer to the [TailwindCSS docs](https://tailwindcss.com/docs/configuration) for general information on configuring TailwindCSS. + +You can refer to the [@roots/bud-tailwindcss documentation](/extensions/bud-tailwindcss) for more information on bud specific concerns. diff --git a/sources/@repo/docs/content/learn/getting-started/adding-typescript.mdx b/sources/@repo/docs/content/learn/getting-started/adding-typescript.mdx new file mode 100644 index 0000000000..33def81186 --- /dev/null +++ b/sources/@repo/docs/content/learn/getting-started/adding-typescript.mdx @@ -0,0 +1,41 @@ +--- +title: Adding TypeScript +description: How to get started with TypeScript +sidebar_label: Adding TypeScript +--- + +## Installing bud.js dependencies + +There are a few options to add support for TypeScript to your application. We recommend the [@roots/bud-swc extension](/extensions/bud-swc). + +```sh npm2yarn +npm install @roots/bud-swc --save-dev +``` + +## Other options + +### @roots/bud-typescript + +[@roots/bud-typescript](/extensions/bud-typescript) adds TypeScript support using the [official TypeScript compiler](https://www.typescriptlang.org/). +The extension supports JavaScript and TypeScript with zero configuration. + +```sh npm2yarn +npm install @roots/bud-typescript --save-dev +``` + +If you want to do type checking during compilation this is probably the best option. + +### @roots/bud-esbuild + +:::info Experimental + +This extension should be considered experimental. Not all features may work. In particular hot module replacement. + +::: + +[@roots/bud-esbuild](/extensions/bud-esbuild) adds TypeScript support using [esbuild](https://esbuild.github.io/). +The extension supports JavaScript and TypeScript with zero configuration. + +```sh npm2yarn +npm install @roots/bud-esbuild --save-dev +``` diff --git a/sources/@repo/docs/content/learn/getting-started/adding-vue.mdx b/sources/@repo/docs/content/learn/getting-started/adding-vue.mdx new file mode 100644 index 0000000000..90982edf06 --- /dev/null +++ b/sources/@repo/docs/content/learn/getting-started/adding-vue.mdx @@ -0,0 +1,43 @@ +--- +title: Adding Vue +description: How to get started with Vue +sidebar_label: Adding Vue +--- + +## Installing bud.js dependencies + +To get started with Vue, install the [@roots/bud-vue](/extensions/bud-vue) extension to your project. + +```bash npm2yarn +npm install @roots/bud-vue --save-dev +``` + +If you need to further customize Vue for your application, reference the [@roots/bud-vue documentation](/extensions/bud-vue). + +## Installing production dependencies + +Vue requires installing `vue` as production dependencies. + +We will try and resolve this for you but it is a good idea to install it as an explicit dependency: + +```bash npm2yarn +npm install vue --save +``` + +## Configuration + +No configuration is required. + +### Using Vue 2 instead of Vue 3 + +A Vue 3 project can just install **@roots/bud** and **@roots/bud-vue** and everything should be perfectly set up. But, at least for now, in order to use Vue 2, you'll need to override the peer dependencies that **@roots/bud-vue** ships with: + +- vue (2.6.14) +- vue-template-compiler (2.6.14) +- vue-loader (15.9.4) + +```sh npm2yarn +npm install vue@2.6.14 vue-template-compiler@2.6.14 vue-loader@15.9.4 --save-dev +``` + +If you need to further customize the provided defaults refer to the [@roots/bud-vue documentation](/extensions/bud-vue). diff --git a/sources/@repo/docs/content/learn/getting-started/adding-wordpress-support.mdx b/sources/@repo/docs/content/learn/getting-started/adding-wordpress-support.mdx new file mode 100644 index 0000000000..227d3a9d4e --- /dev/null +++ b/sources/@repo/docs/content/learn/getting-started/adding-wordpress-support.mdx @@ -0,0 +1,34 @@ +--- +title: Adding WordPress support +description: How to get started with WordPress +sidebar_label: Adding WordPress support +--- + +## Installing bud.js dependencies + +To get started with WordPress, install the [@roots/bud-preset-wordpress preset](/extensions/bud-preset-wordpress) along with a compatible compiler: + +- [@roots/bud-babel](/extensions/bud-babel) +- [@roots/bud-esbuild](/extensions/bud-esbuild) +- [@roots/bud-swc](/extensions/bud-swc) +- [@roots/bud-typescript](/extensions/bud-typescript) + +We recommend using [@roots/bud-swc](/extensions/bud-swc): + +```bash npm2yarn +npm install @roots/bud-preset-wordpress @roots/bud-swc --save-dev +``` + +## Included extensions + +The [@roots/bud-preset-wordpress preset](/extensions/bud-preset-wordpress) includes the following extensions: + +- [@roots/bud-react](/extensions/bud-react) +- @roots/bud-wordpress-dependencies +- @roots/bud-wordpress-externals +- @roots/bud-wordpress-theme-json +- @roots/wordpress-hmr + +## Configuration + +For more information on configuring WordPress, see the [@roots/bud-preset-wordpress documentation](/extensions/bud-preset-wordpress). diff --git a/sources/@repo/docs/content/guides/create-bud-app.mdx b/sources/@repo/docs/content/learn/getting-started/create-bud-app.mdx similarity index 99% rename from sources/@repo/docs/content/guides/create-bud-app.mdx rename to sources/@repo/docs/content/learn/getting-started/create-bud-app.mdx index b11544788c..a0fb3f27b5 100644 --- a/sources/@repo/docs/content/guides/create-bud-app.mdx +++ b/sources/@repo/docs/content/learn/getting-started/create-bud-app.mdx @@ -2,7 +2,6 @@ title: create-bud-app description: Create a new project using our convenient CLI sidebar_label: create-bud-app -slug: create-bud-app --- ## Overview diff --git a/sources/@repo/docs/content/learn/getting-started/index.mdx b/sources/@repo/docs/content/learn/getting-started/index.mdx new file mode 100644 index 0000000000..35999f7629 --- /dev/null +++ b/sources/@repo/docs/content/learn/getting-started/index.mdx @@ -0,0 +1,63 @@ +--- +title: Installation +description: Installing bud.js +sidebar_label: Installation +--- + +**bud.js** is a web-focused build tool with add-on support for Babel, React, PostCSS, Sass, Typescript, esbuild, ESLint, Prettier, and more. + +## Requirements + +
+
+ +
+
+ +## Creating a new project + +The easiest way to get started with bud.js is to use the [create-bud-app command](/learn/getting-started/create-bud-app). + +```bash +npx create-bud-app my-app +``` + +## Adding to an existing project + +Add **@roots/bud** as a development dependency using your choice of package manager. + +```bash npm2yarn +npm install @roots/bud --save-dev +``` + +:::info + +If you are using pnpm add `--public-hoist-pattern=*` to the installation command and [use our .pnpmfile.cjs compatibility shim](/learn/general-use/pnpm#pnpmfilecjs-compatibilty-shim). + +::: + +## Building your project + +If your project's entrypoint is located at `./src/index.js` you can now compile it using the [bud build](/cli/build/index.mdx) command. + +```bash npm2yarn +npm run bud build +``` + +No configuration is required. The bundled code will be output to `./dist/*`. + +If your application entrypoint is not located at `./src/index.js`, you can learn about how to configure it with [bud.entry](/reference/bud.entry) it in the [Entrypoints guide](/learn/config/entrypoints). + +## Upgrading bud.js + +In general, all dependencies with the `@roots/*` namespace should share the same version. + +To make it easy to keep versions in sync you can use the [bud upgrade](/cli/upgrade.mdx) command. + +```bash npm2yarn +npm run bud upgrade +``` diff --git a/sources/@repo/docs/content/guides/modules/css-modules.mdx b/sources/@repo/docs/content/learn/modules/css-modules.mdx similarity index 100% rename from sources/@repo/docs/content/guides/modules/css-modules.mdx rename to sources/@repo/docs/content/learn/modules/css-modules.mdx diff --git a/sources/@repo/docs/content/guides/modules/js-modules.mdx b/sources/@repo/docs/content/learn/modules/js-modules.mdx similarity index 96% rename from sources/@repo/docs/content/guides/modules/js-modules.mdx rename to sources/@repo/docs/content/learn/modules/js-modules.mdx index 7afa60e62e..962f7dfd6d 100644 --- a/sources/@repo/docs/content/guides/modules/js-modules.mdx +++ b/sources/@repo/docs/content/learn/modules/js-modules.mdx @@ -60,8 +60,8 @@ You can import css using the `import` keyword. import '@src/styles/app.css' ``` -This is essentially the same as adding the css file to the [bud.entry](/docs/bud.entry) call in your -[bud.config.js file](../configure). But, when considered alongside [dynamic imports](#dynamic-imports) it is much more powerful. +This is essentially the same as adding the css file to the [bud.entry](/reference/bud.entry) call in your +[bud.config.js file](/learn/config/files/bud.config). But, when considered alongside [dynamic imports](#dynamic-imports) it is much more powerful. ### Conditional css diff --git a/sources/@repo/docs/content/guides/modules/static-assets.mdx b/sources/@repo/docs/content/learn/modules/static-assets.mdx similarity index 93% rename from sources/@repo/docs/content/guides/modules/static-assets.mdx rename to sources/@repo/docs/content/learn/modules/static-assets.mdx index 6b395cd799..9394014040 100644 --- a/sources/@repo/docs/content/guides/modules/static-assets.mdx +++ b/sources/@repo/docs/content/learn/modules/static-assets.mdx @@ -14,7 +14,7 @@ It is straight forward to reference assets from application scripts and styleshe ### With an alias You can use aliases to reference common directories. **bud.js** comes configured with a built-in `@src` alias, but more can easily be added. -See the [bud.alias documentation](/docs/bud.alias) for more information on this function. +See the [bud.alias documentation](/reference/bud.alias) for more information on this function. @@ -66,7 +66,7 @@ body { ### Using an absolute path -Assets can be referenced using an absolute path. The root url is [the @src directory](/docs/bud.path). +Assets can be referenced using an absolute path. The root url is [the @src directory](/reference/bud.path). diff --git a/sources/@repo/docs/content/pages/index.tsx b/sources/@repo/docs/content/pages/index.tsx index d718e9fab3..9273f5d843 100644 --- a/sources/@repo/docs/content/pages/index.tsx +++ b/sources/@repo/docs/content/pages/index.tsx @@ -1,16 +1,38 @@ -/* eslint-disable simple-import-sort/imports */ +import Link from '@docusaurus/Link' +import styles from '@site/src/components/mast/index.module.css' +import {Sponsors} from '@site/src/components/sponsors' import Layout from '@theme/Layout' +import clsx from 'clsx' import React from 'react' -import {Features} from '@site/src/components/features' -import {Mast} from '@site/src/components/mast' -import {Sponsors} from '@site/src/components/sponsors' - const Home = () => { return ( - - +
+
+

+ Configurable, extensible build tools for modern single and + multi-page web applications +

+ +
+ + Get started{` `}→ + + + + API reference{` `}→ + +
+
+
+ ) diff --git a/sources/@repo/docs/content/docs/bud.after.mdx b/sources/@repo/docs/content/reference/bud.after.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.after.mdx rename to sources/@repo/docs/content/reference/bud.after.mdx diff --git a/sources/@repo/docs/content/docs/bud.alias.mdx b/sources/@repo/docs/content/reference/bud.alias.mdx similarity index 92% rename from sources/@repo/docs/content/docs/bud.alias.mdx rename to sources/@repo/docs/content/reference/bud.alias.mdx index f8ff707702..dd7597d5a3 100644 --- a/sources/@repo/docs/content/docs/bud.alias.mdx +++ b/sources/@repo/docs/content/reference/bud.alias.mdx @@ -5,7 +5,7 @@ description: Register shorthand for resolving modules **bud.alias** is a helper function for creating aliases. Unlike paths, aliases may be used in your application scripts and stylesheets. -**Aliases must be absolute**, so it makes sense to use [bud.path](/docs/bud.path) when defining them: +**Aliases must be absolute**, so it makes sense to use [bud.path](/reference/bud.path) when defining them: ```ts bud.alias('@components', bud.path('@src/components')) @@ -36,7 +36,7 @@ Out-of-the-box you can reference your source directory with `@src` and output di ## Naming aliases -The naming of **bud.alias** handles is not restrictive the way it is with [bud.path](/docs/bud.path). You are free to start an alias with any character you like. +The naming of **bud.alias** handles is not restrictive the way it is with [bud.path](/reference/bud.path). You are free to start an alias with any character you like. One popular convention is to reference the source directory with `@`: diff --git a/sources/@repo/docs/content/docs/bud.assets/index.mdx b/sources/@repo/docs/content/reference/bud.assets/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.assets/index.mdx rename to sources/@repo/docs/content/reference/bud.assets/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.bundle.mdx b/sources/@repo/docs/content/reference/bud.bundle.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.bundle.mdx rename to sources/@repo/docs/content/reference/bud.bundle.mdx diff --git a/sources/@repo/docs/content/docs/bud.compilePaths/index.mdx b/sources/@repo/docs/content/reference/bud.compilePaths/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.compilePaths/index.mdx rename to sources/@repo/docs/content/reference/bud.compilePaths/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.config/index.mdx b/sources/@repo/docs/content/reference/bud.config/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.config/index.mdx rename to sources/@repo/docs/content/reference/bud.config/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.copyDir/index.mdx b/sources/@repo/docs/content/reference/bud.copyDir/index.mdx similarity index 83% rename from sources/@repo/docs/content/docs/bud.copyDir/index.mdx rename to sources/@repo/docs/content/reference/bud.copyDir/index.mdx index 8c59656f3e..842d47f7da 100644 --- a/sources/@repo/docs/content/docs/bud.copyDir/index.mdx +++ b/sources/@repo/docs/content/reference/bud.copyDir/index.mdx @@ -18,5 +18,5 @@ import Usage from '@site/../../@roots/bud-api/docs/copyDir/usage.md' ## Related -- [bud.copyFile](/docs/bud.copyFile) -- [bud.assets](/docs/bud.assets) +- [bud.copyFile](/reference/bud.copyFile) +- [bud.assets](/reference/bud.assets) diff --git a/sources/@repo/docs/content/docs/bud.copyFile/index.mdx b/sources/@repo/docs/content/reference/bud.copyFile/index.mdx similarity index 83% rename from sources/@repo/docs/content/docs/bud.copyFile/index.mdx rename to sources/@repo/docs/content/reference/bud.copyFile/index.mdx index 02ac004453..489b9238dd 100644 --- a/sources/@repo/docs/content/docs/bud.copyFile/index.mdx +++ b/sources/@repo/docs/content/reference/bud.copyFile/index.mdx @@ -18,5 +18,5 @@ import Usage from '@site/../../@roots/bud-api/docs/copyFile/usage.md' ## Related -- [bud.copyDir](/docs/bud.copyDir) -- [bud.assets](/docs/bud.assets) +- [bud.copyDir](/reference/bud.copyDir) +- [bud.assets](/reference/bud.assets) diff --git a/sources/@repo/docs/content/docs/bud.define/index.mdx b/sources/@repo/docs/content/reference/bud.define/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.define/index.mdx rename to sources/@repo/docs/content/reference/bud.define/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.devtool.mdx b/sources/@repo/docs/content/reference/bud.devtool.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.devtool.mdx rename to sources/@repo/docs/content/reference/bud.devtool.mdx diff --git a/sources/@repo/docs/content/docs/bud.entry/index.mdx b/sources/@repo/docs/content/reference/bud.entry/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.entry/index.mdx rename to sources/@repo/docs/content/reference/bud.entry/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.env.mdx b/sources/@repo/docs/content/reference/bud.env.mdx similarity index 97% rename from sources/@repo/docs/content/docs/bud.env.mdx rename to sources/@repo/docs/content/reference/bud.env.mdx index 5788a6357c..ee450700c3 100644 --- a/sources/@repo/docs/content/docs/bud.env.mdx +++ b/sources/@repo/docs/content/reference/bud.env.mdx @@ -25,7 +25,7 @@ bud.env.is('APP_ENV', 'production') ## Accessing env values from within a template -Values defined in the application `.env` file are available within HTML templates ([see **bud.html** for more information on HTML templating](/docs/bud.html)). +Values defined in the application `.env` file are available within HTML templates ([see **bud.html** for more information on HTML templating](/reference/bud.html)). ## Accessing env values from within the application diff --git a/sources/@repo/docs/content/docs/bud.experiments.mdx b/sources/@repo/docs/content/reference/bud.experiments.mdx similarity index 87% rename from sources/@repo/docs/content/docs/bud.experiments.mdx rename to sources/@repo/docs/content/reference/bud.experiments.mdx index d4cbaa8bd9..7452bc1473 100644 --- a/sources/@repo/docs/content/docs/bud.experiments.mdx +++ b/sources/@repo/docs/content/reference/bud.experiments.mdx @@ -13,13 +13,13 @@ a PR that implements the change you would like to see. :::info -If you want to configure `buildHttp` you should consider using [the `bud.http` interface](/guides/general-use/esmodules). +If you want to configure `buildHttp` you should consider using [the `bud.http` interface](/learn/general-use/esmodules). ::: :::info -If you want to configure `outputModule` you should consider using [the `bud.esm` interface](/guides/general-use/esmodules). +If you want to configure `outputModule` you should consider using [the `bud.esm` interface](/learn/general-use/esmodules). ::: diff --git a/sources/@repo/docs/content/docs/bud.externals.mdx b/sources/@repo/docs/content/reference/bud.externals.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.externals.mdx rename to sources/@repo/docs/content/reference/bud.externals.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/copy.mdx b/sources/@repo/docs/content/reference/bud.fs/copy.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/copy.mdx rename to sources/@repo/docs/content/reference/bud.fs/copy.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/dir.mdx b/sources/@repo/docs/content/reference/bud.fs/dir.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/dir.mdx rename to sources/@repo/docs/content/reference/bud.fs/dir.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/exists.mdx b/sources/@repo/docs/content/reference/bud.fs/exists.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/exists.mdx rename to sources/@repo/docs/content/reference/bud.fs/exists.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/find.mdx b/sources/@repo/docs/content/reference/bud.fs/find.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/find.mdx rename to sources/@repo/docs/content/reference/bud.fs/find.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/index.mdx b/sources/@repo/docs/content/reference/bud.fs/index.mdx similarity index 87% rename from sources/@repo/docs/content/docs/bud.fs/index.mdx rename to sources/@repo/docs/content/reference/bud.fs/index.mdx index 27194c146d..ce0774173c 100644 --- a/sources/@repo/docs/content/docs/bud.fs/index.mdx +++ b/sources/@repo/docs/content/reference/bud.fs/index.mdx @@ -20,11 +20,11 @@ await source.write(`hello.txt`, `hello world`) // write `hello world` to src/hel ## bud.fs.json -Utilities for reading and writing json. See [bud.fs.json documentation](/docs/bud.fs/yml) for more information. +Utilities for reading and writing json. See [bud.fs.json documentation](/reference/bud.fs/yml) for more information. ## bud.fs.yml -Utilities for reading and writing yml. See [bud.fs.yml documentation](/docs/bud.fs/yml) for more information. +Utilities for reading and writing yml. See [bud.fs.yml documentation](/reference/bud.fs/yml) for more information. ## bud.fs.s3 @@ -46,4 +46,4 @@ bud.fs .upload() ``` -[See bud.fs.s3 documentation](/docs/bud.fs/s3) for more information on how to use these features. +[See bud.fs.s3 documentation](/reference/bud.fs/s3) for more information on how to use these features. diff --git a/sources/@repo/docs/content/docs/bud.fs/inspect.mdx b/sources/@repo/docs/content/reference/bud.fs/inspect.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/inspect.mdx rename to sources/@repo/docs/content/reference/bud.fs/inspect.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/inspectTree.mdx b/sources/@repo/docs/content/reference/bud.fs/inspectTree.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/inspectTree.mdx rename to sources/@repo/docs/content/reference/bud.fs/inspectTree.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/json.mdx b/sources/@repo/docs/content/reference/bud.fs/json.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/json.mdx rename to sources/@repo/docs/content/reference/bud.fs/json.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/list.mdx b/sources/@repo/docs/content/reference/bud.fs/list.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/list.mdx rename to sources/@repo/docs/content/reference/bud.fs/list.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/move.mdx b/sources/@repo/docs/content/reference/bud.fs/move.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/move.mdx rename to sources/@repo/docs/content/reference/bud.fs/move.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/read.mdx b/sources/@repo/docs/content/reference/bud.fs/read.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/read.mdx rename to sources/@repo/docs/content/reference/bud.fs/read.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/s3/delete.mdx b/sources/@repo/docs/content/reference/bud.fs/s3/delete.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/s3/delete.mdx rename to sources/@repo/docs/content/reference/bud.fs/s3/delete.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/s3/exists.mdx b/sources/@repo/docs/content/reference/bud.fs/s3/exists.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/s3/exists.mdx rename to sources/@repo/docs/content/reference/bud.fs/s3/exists.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/s3/index.mdx b/sources/@repo/docs/content/reference/bud.fs/s3/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/s3/index.mdx rename to sources/@repo/docs/content/reference/bud.fs/s3/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/s3/list.mdx b/sources/@repo/docs/content/reference/bud.fs/s3/list.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/s3/list.mdx rename to sources/@repo/docs/content/reference/bud.fs/s3/list.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/s3/read.mdx b/sources/@repo/docs/content/reference/bud.fs/s3/read.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/s3/read.mdx rename to sources/@repo/docs/content/reference/bud.fs/s3/read.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/s3/setBucket.mdx b/sources/@repo/docs/content/reference/bud.fs/s3/setBucket.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/s3/setBucket.mdx rename to sources/@repo/docs/content/reference/bud.fs/s3/setBucket.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/s3/setCredentials.mdx b/sources/@repo/docs/content/reference/bud.fs/s3/setCredentials.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/s3/setCredentials.mdx rename to sources/@repo/docs/content/reference/bud.fs/s3/setCredentials.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/s3/setEndpoint.mdx b/sources/@repo/docs/content/reference/bud.fs/s3/setEndpoint.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/s3/setEndpoint.mdx rename to sources/@repo/docs/content/reference/bud.fs/s3/setEndpoint.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/s3/setPublic.mdx b/sources/@repo/docs/content/reference/bud.fs/s3/setPublic.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/s3/setPublic.mdx rename to sources/@repo/docs/content/reference/bud.fs/s3/setPublic.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/s3/setRegion.mdx b/sources/@repo/docs/content/reference/bud.fs/s3/setRegion.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/s3/setRegion.mdx rename to sources/@repo/docs/content/reference/bud.fs/s3/setRegion.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/s3/write.mdx b/sources/@repo/docs/content/reference/bud.fs/s3/write.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/s3/write.mdx rename to sources/@repo/docs/content/reference/bud.fs/s3/write.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/symlink.mdx b/sources/@repo/docs/content/reference/bud.fs/symlink.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/symlink.mdx rename to sources/@repo/docs/content/reference/bud.fs/symlink.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/write.mdx b/sources/@repo/docs/content/reference/bud.fs/write.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/write.mdx rename to sources/@repo/docs/content/reference/bud.fs/write.mdx diff --git a/sources/@repo/docs/content/docs/bud.fs/yml.mdx b/sources/@repo/docs/content/reference/bud.fs/yml.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.fs/yml.mdx rename to sources/@repo/docs/content/reference/bud.fs/yml.mdx diff --git a/sources/@repo/docs/content/docs/bud.get.mdx b/sources/@repo/docs/content/reference/bud.get.mdx similarity index 82% rename from sources/@repo/docs/content/docs/bud.get.mdx rename to sources/@repo/docs/content/reference/bud.get.mdx index 72549f5cd8..29834b7b1e 100644 --- a/sources/@repo/docs/content/docs/bud.get.mdx +++ b/sources/@repo/docs/content/reference/bud.get.mdx @@ -46,6 +46,6 @@ export default async bud => ## Related -| Utility | Description | -| -------------------------- | ----------------------- | -| [bud.make](/docs/bud.make) | Create a child compiler | +| Utility | Description | +| ------------------------------- | ----------------------- | +| [bud.make](/reference/bud.make) | Create a child compiler | diff --git a/sources/@repo/docs/content/docs/bud.glob.mdx b/sources/@repo/docs/content/reference/bud.glob.mdx similarity index 91% rename from sources/@repo/docs/content/docs/bud.glob.mdx rename to sources/@repo/docs/content/reference/bud.glob.mdx index b95b5f379f..855988232b 100644 --- a/sources/@repo/docs/content/docs/bud.glob.mdx +++ b/sources/@repo/docs/content/reference/bud.glob.mdx @@ -3,7 +3,7 @@ title: bud.glob description: Globbing function --- -Glob for matching files. This function is asynchronous but there is a synchronous version provided by [bud.globSync](/docs/bud.globSync) +Glob for matching files. This function is asynchronous but there is a synchronous version provided by [bud.globSync](/reference/bud.globSync) ## Usage @@ -25,7 +25,7 @@ or: const results = await bud.glob(['**/*.json', '**/*.yml']) ``` -This function is compatible with the base handles used with [bud.path](/docs/bud.path). +This function is compatible with the base handles used with [bud.path](/reference/bud.path). So, the following would search for `js` files within the **@src** directory: diff --git a/sources/@repo/docs/content/docs/bud.globSync.mdx b/sources/@repo/docs/content/reference/bud.globSync.mdx similarity index 88% rename from sources/@repo/docs/content/docs/bud.globSync.mdx rename to sources/@repo/docs/content/reference/bud.globSync.mdx index 245a82528e..e4053126ca 100644 --- a/sources/@repo/docs/content/docs/bud.globSync.mdx +++ b/sources/@repo/docs/content/reference/bud.globSync.mdx @@ -3,7 +3,7 @@ title: bud.globSync description: Globbing function --- -Glob for matching files. This function is synchronous but there is an asynchronous version provided by [bud.glob](/docs/bud.glob). The asynchronous version should be preferred. +Glob for matching files. This function is synchronous but there is an asynchronous version provided by [bud.glob](/reference/bud.glob). The asynchronous version should be preferred. ## Usage @@ -25,7 +25,7 @@ or: const results = bud.globSync(['**/*.json', '**/*.yml']) ``` -This function is compatible with the base handles used with [bud.path](/docs/bud.path). +This function is compatible with the base handles used with [bud.path](/reference/bud.path). So, the following would search for `js` files within the **@src** directory: diff --git a/sources/@repo/docs/content/docs/bud.hash.mdx b/sources/@repo/docs/content/reference/bud.hash.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.hash.mdx rename to sources/@repo/docs/content/reference/bud.hash.mdx diff --git a/sources/@repo/docs/content/docs/bud.hooks/index.mdx b/sources/@repo/docs/content/reference/bud.hooks/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.hooks/index.mdx rename to sources/@repo/docs/content/reference/bud.hooks/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.html/index.mdx b/sources/@repo/docs/content/reference/bud.html/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.html/index.mdx rename to sources/@repo/docs/content/reference/bud.html/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.make.mdx b/sources/@repo/docs/content/reference/bud.make.mdx similarity index 87% rename from sources/@repo/docs/content/docs/bud.make.mdx rename to sources/@repo/docs/content/reference/bud.make.mdx index 207092182d..ef6f122caf 100644 --- a/sources/@repo/docs/content/docs/bud.make.mdx +++ b/sources/@repo/docs/content/reference/bud.make.mdx @@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem' Create a new, configurable instance of bud.js. -For more context on how this might be useful check out [the guide on multi-instance configurations](/guides/general-use/multi-instance). +For more context on how this might be useful check out [the guide on multi-instance configurations](/learn/general-use/multi-instance). ## Usage @@ -47,7 +47,7 @@ export default async bud => { When loading output from multiple instances on a single page you need to be aware of the potential for runtime conflicts. -If you are using the [bud.runtime](/docs/bud.runtime) function, you likely want to use the value `single` (the default value). +If you are using the [bud.runtime](/reference/bud.runtime) function, you likely want to use the value `single` (the default value). Beyond that, it may be helpful to know that each instance of bud.js declares all previous instances as _dependencies_. So, in the above examples, `compiler-a` would be a dependency of `compiler-b`. If you added another instance, `compiler-c`, it would be dependent on both `compiler-a` and `compiler-b`. @@ -86,8 +86,8 @@ bud.get('compiler-c').hooks.on('build.dependencies', ['compiler-a']) Related: -- [bud.get](/docs/bud.get) +- [bud.get](/reference/bud.get) Guides: -- [multi-instance guide](/guides/general-use/multi-instance) +- [multi-instance guide](/learn/general-use/multi-instance) diff --git a/sources/@repo/docs/content/docs/bud.minimize/index.mdx b/sources/@repo/docs/content/reference/bud.minimize/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.minimize/index.mdx rename to sources/@repo/docs/content/reference/bud.minimize/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.mode/bud.isDevelopment.mdx b/sources/@repo/docs/content/reference/bud.mode/bud.isDevelopment.mdx similarity index 62% rename from sources/@repo/docs/content/docs/bud.mode/bud.isDevelopment.mdx rename to sources/@repo/docs/content/reference/bud.mode/bud.isDevelopment.mdx index fd4e7ec141..529496b155 100644 --- a/sources/@repo/docs/content/docs/bud.mode/bud.isDevelopment.mdx +++ b/sources/@repo/docs/content/reference/bud.mode/bud.isDevelopment.mdx @@ -5,7 +5,7 @@ description: Property that is `true` when bud.mode is `development` # bud.isDevelopment -**Boolean** property which is `true` when [bud.mode](/docs/bud.mode/) is `development` +**Boolean** property which is `true` when [bud.mode](/reference/bud.mode/) is `development` ## Usage @@ -15,7 +15,7 @@ Very useful in conditionals: export default async bud => bud.isDevelopment && bud.devtool('source-map') ``` -Pairs well with [bud.when](/docs/bud.when): +Pairs well with [bud.when](/reference/bud.when): ```js {2} title=bud.config.js export default async bud => @@ -24,5 +24,5 @@ export default async bud => ## See also -- [bud.mode](/docs/bud.mode/) -- [bud.isProduction](/docs/bud.mode/bud.isProduction) +- [bud.mode](/reference/bud.mode/) +- [bud.isProduction](/reference/bud.mode/bud.isProduction) diff --git a/sources/@repo/docs/content/docs/bud.mode/bud.isProduction.mdx b/sources/@repo/docs/content/reference/bud.mode/bud.isProduction.mdx similarity index 60% rename from sources/@repo/docs/content/docs/bud.mode/bud.isProduction.mdx rename to sources/@repo/docs/content/reference/bud.mode/bud.isProduction.mdx index fa284ef04f..8a98ba07c6 100644 --- a/sources/@repo/docs/content/docs/bud.mode/bud.isProduction.mdx +++ b/sources/@repo/docs/content/reference/bud.mode/bud.isProduction.mdx @@ -5,7 +5,7 @@ description: Property that is `true` when bud.mode is `production` # bud.isProduction -**Boolean** property which is `true` when [bud.mode](/docs/bud.mode/) is `production` +**Boolean** property which is `true` when [bud.mode](/reference/bud.mode/) is `production` ## Usage @@ -15,7 +15,7 @@ Very useful in conditionals: export default async bud => bud.isProduction && bud.devtool('source-map') ``` -Pairs well with [bud.when](/docs/bud.when): +Pairs well with [bud.when](/reference/bud.when): ```js {2} title=bud.config.js bud.when(bud.isProduction, bud => bud.minify()) @@ -23,5 +23,5 @@ bud.when(bud.isProduction, bud => bud.minify()) ## See also -- [bud.mode](/docs/bud.mode/) -- [bud.isDevelopment](/docs/bud.mode/bud.isDevelopment) +- [bud.mode](/reference/bud.mode/) +- [bud.isDevelopment](/reference/bud.mode/bud.isDevelopment) diff --git a/sources/@repo/docs/content/docs/bud.mode/index.mdx b/sources/@repo/docs/content/reference/bud.mode/index.mdx similarity index 55% rename from sources/@repo/docs/content/docs/bud.mode/index.mdx rename to sources/@repo/docs/content/reference/bud.mode/index.mdx index 21e894c69d..a7c03f163f 100644 --- a/sources/@repo/docs/content/docs/bud.mode/index.mdx +++ b/sources/@repo/docs/content/reference/bud.mode/index.mdx @@ -7,7 +7,7 @@ Specify if a build is being run in a `production` or `development` context. **bud.mode** will always be either `production` or `development`. -When running bud [using the cli](/guides/cli/): +When running bud [using the cli](/learn/cli/): -- [bud build production](/guides/cli/build) will always run in `production`. -- [bud build development](/guides/cli/build) will always run in `development`. +- [bud build production](/learn/cli/build) will always run in `production`. +- [bud build development](/learn/cli/build) will always run in `development`. diff --git a/sources/@repo/docs/content/docs/bud.path.mdx b/sources/@repo/docs/content/reference/bud.path.mdx similarity index 86% rename from sources/@repo/docs/content/docs/bud.path.mdx rename to sources/@repo/docs/content/reference/bud.path.mdx index 961985700d..7a9402db91 100644 --- a/sources/@repo/docs/content/docs/bud.path.mdx +++ b/sources/@repo/docs/content/reference/bud.path.mdx @@ -28,6 +28,15 @@ The following is a table containing `string` values which fulfill a special role | **@storage** | cache/artifact storage directory | `./.budfiles` | | **@modules** | modules directory | `./node_modules` | +:::note + +The `@storage` path is used to store cache and artifact files. It should not be set with `bud.setPath`. There is a lot of logic +that depends on this path being set, and much of it executes before any user configuration files are loaded. + +If you want to customize the storage path, you should use the **--storage** flag instead. + +::: + When one of these handles is used at **the beginning of a string path** (or the first segment in a multi-segment path), the path will be prefixed with the corresponding directory. diff --git a/sources/@repo/docs/content/docs/bud.pipe.mdx b/sources/@repo/docs/content/reference/bud.pipe.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.pipe.mdx rename to sources/@repo/docs/content/reference/bud.pipe.mdx diff --git a/sources/@repo/docs/content/docs/bud.provide/index.mdx b/sources/@repo/docs/content/reference/bud.provide/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.provide/index.mdx rename to sources/@repo/docs/content/reference/bud.provide/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.proxy/index.mdx b/sources/@repo/docs/content/reference/bud.proxy/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.proxy/index.mdx rename to sources/@repo/docs/content/reference/bud.proxy/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.proxy/modifying-the-response-body.mdx b/sources/@repo/docs/content/reference/bud.proxy/modifying-the-response-body.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.proxy/modifying-the-response-body.mdx rename to sources/@repo/docs/content/reference/bud.proxy/modifying-the-response-body.mdx diff --git a/sources/@repo/docs/content/docs/bud.proxy/options.mdx b/sources/@repo/docs/content/reference/bud.proxy/options.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.proxy/options.mdx rename to sources/@repo/docs/content/reference/bud.proxy/options.mdx diff --git a/sources/@repo/docs/content/docs/bud.publicPath.mdx b/sources/@repo/docs/content/reference/bud.publicPath.mdx similarity index 66% rename from sources/@repo/docs/content/docs/bud.publicPath.mdx rename to sources/@repo/docs/content/reference/bud.publicPath.mdx index 788ab86bdd..879291ee84 100644 --- a/sources/@repo/docs/content/docs/bud.publicPath.mdx +++ b/sources/@repo/docs/content/reference/bud.publicPath.mdx @@ -5,7 +5,7 @@ description: Get the application public path. Get the application public path. -To set the path itself you may use [bud.setPublicPath](/docs/bud.setPublicPath). +To set the path itself you may use [bud.setPublicPath](/reference/bud.setPublicPath). ## Usage diff --git a/sources/@repo/docs/content/docs/bud.runtime.mdx b/sources/@repo/docs/content/reference/bud.runtime.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.runtime.mdx rename to sources/@repo/docs/content/reference/bud.runtime.mdx diff --git a/sources/@repo/docs/content/docs/bud.serve/index.mdx b/sources/@repo/docs/content/reference/bud.serve/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.serve/index.mdx rename to sources/@repo/docs/content/reference/bud.serve/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.serve/setting-options.mdx b/sources/@repo/docs/content/reference/bud.serve/setting-options.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.serve/setting-options.mdx rename to sources/@repo/docs/content/reference/bud.serve/setting-options.mdx diff --git a/sources/@repo/docs/content/docs/bud.serve/setting-the-origin.mdx b/sources/@repo/docs/content/reference/bud.serve/setting-the-origin.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.serve/setting-the-origin.mdx rename to sources/@repo/docs/content/reference/bud.serve/setting-the-origin.mdx diff --git a/sources/@repo/docs/content/docs/bud.setPath.mdx b/sources/@repo/docs/content/reference/bud.setPath.mdx similarity index 83% rename from sources/@repo/docs/content/docs/bud.setPath.mdx rename to sources/@repo/docs/content/reference/bud.setPath.mdx index 22aae75b5a..417ac03f15 100644 --- a/sources/@repo/docs/content/docs/bud.setPath.mdx +++ b/sources/@repo/docs/content/reference/bud.setPath.mdx @@ -3,7 +3,7 @@ title: bud.setPath description: Set application paths --- -You can use **bud.setPath** to set a [bud.path](/docs/bud.path) handle. This documentation probably makes more sense if you've read the [bud.path](/docs/bud.path) documentation. +You can use **bud.setPath** to set a [bud.path](/reference/bud.path) handle. This documentation probably makes more sense if you've read the [bud.path](/reference/bud.path) documentation. ## Defining new handles diff --git a/sources/@repo/docs/content/docs/bud.setProxyUrl/index.mdx b/sources/@repo/docs/content/reference/bud.setProxyUrl/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.setProxyUrl/index.mdx rename to sources/@repo/docs/content/reference/bud.setProxyUrl/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.setPublicPath.mdx b/sources/@repo/docs/content/reference/bud.setPublicPath.mdx similarity index 77% rename from sources/@repo/docs/content/docs/bud.setPublicPath.mdx rename to sources/@repo/docs/content/reference/bud.setPublicPath.mdx index c7f72fb600..2f753403b4 100644 --- a/sources/@repo/docs/content/docs/bud.setPublicPath.mdx +++ b/sources/@repo/docs/content/reference/bud.setPublicPath.mdx @@ -5,7 +5,7 @@ description: Set the public path. Set the public path. By default the public path will be `''` in production and `/` in development. -To get the value set by this function you should use [publicPath](/docs/bud.publicPath) +To get the value set by this function you should use [publicPath](/reference/bud.publicPath) ## Usage @@ -23,14 +23,6 @@ bud.setPublicPath(publicPath => { }) ``` -## Environment variable - -You may set the public path using an environment variable: `APP_PUBLIC_PATH`. - -```env -APP_PUBLIC_PATH=/assets/ -``` - ## CLI You may set the public path using the CLI using the `--publicPath` flag: diff --git a/sources/@repo/docs/content/docs/bud.setPublicProxyUrl/index.mdx b/sources/@repo/docs/content/reference/bud.setPublicProxyUrl/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.setPublicProxyUrl/index.mdx rename to sources/@repo/docs/content/reference/bud.setPublicProxyUrl/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.setPublicUrl/index.mdx b/sources/@repo/docs/content/reference/bud.setPublicUrl/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.setPublicUrl/index.mdx rename to sources/@repo/docs/content/reference/bud.setPublicUrl/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.setUrl/index.mdx b/sources/@repo/docs/content/reference/bud.setUrl/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.setUrl/index.mdx rename to sources/@repo/docs/content/reference/bud.setUrl/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.sh.mdx b/sources/@repo/docs/content/reference/bud.sh.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.sh.mdx rename to sources/@repo/docs/content/reference/bud.sh.mdx diff --git a/sources/@repo/docs/content/docs/bud.splitChunks.mdx b/sources/@repo/docs/content/reference/bud.splitChunks.mdx similarity index 71% rename from sources/@repo/docs/content/docs/bud.splitChunks.mdx rename to sources/@repo/docs/content/reference/bud.splitChunks.mdx index 70f87a7c54..928f1de984 100644 --- a/sources/@repo/docs/content/docs/bud.splitChunks.mdx +++ b/sources/@repo/docs/content/reference/bud.splitChunks.mdx @@ -13,4 +13,4 @@ bud.splitChunks() ## Options -[bud.splitChunks](/docs/bud.splitChunks) takes any parameter Webpack does. +[bud.splitChunks](/reference/bud.splitChunks) takes any parameter Webpack does. diff --git a/sources/@repo/docs/content/docs/bud.tap.mdx b/sources/@repo/docs/content/reference/bud.tap.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.tap.mdx rename to sources/@repo/docs/content/reference/bud.tap.mdx diff --git a/sources/@repo/docs/content/docs/bud.tapAsync.mdx b/sources/@repo/docs/content/reference/bud.tapAsync.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.tapAsync.mdx rename to sources/@repo/docs/content/reference/bud.tapAsync.mdx diff --git a/sources/@repo/docs/content/docs/bud.use.mdx b/sources/@repo/docs/content/reference/bud.use.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.use.mdx rename to sources/@repo/docs/content/reference/bud.use.mdx diff --git a/sources/@repo/docs/content/docs/bud.watch/index.mdx b/sources/@repo/docs/content/reference/bud.watch/index.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.watch/index.mdx rename to sources/@repo/docs/content/reference/bud.watch/index.mdx diff --git a/sources/@repo/docs/content/docs/bud.when.mdx b/sources/@repo/docs/content/reference/bud.when.mdx similarity index 100% rename from sources/@repo/docs/content/docs/bud.when.mdx rename to sources/@repo/docs/content/reference/bud.when.mdx diff --git a/sources/@repo/docs/netlify.toml b/sources/@repo/docs/netlify.toml index e987186deb..74e453db4a 100644 --- a/sources/@repo/docs/netlify.toml +++ b/sources/@repo/docs/netlify.toml @@ -16,8 +16,26 @@ force = true [[redirects]] - from = "https://bud.js.org/docs/bud.template" - to = "https://bud.js.org/docs/bud.html" + from = "https://bud.js.org/blog/tags/release" + to = "https://bud.js.org/releases" + status = 301 + force = true + +[[redirects]] + from = "https://bud.js.org/blog/*" + to = "https://bud.js.org/releases/:splat" + status = 301 + force = true + +[[redirects]] + from = "https://bud.js.org/guides/general-use/multi-compiler" + to = "https://bud.js.org/guides/general-use/multi-instance" + status = 301 + force = true + +[[redirects]] + from = "https://bud.js.org/guides/general-use/transpiler-sources" + to = "https://bud.js.org/guides/general-use/compiler-sources" status = 301 force = true @@ -26,3 +44,45 @@ to = "https://bud.js.org/extensions/bud-preset-wordpress" status = 301 force = true + +[[redirects]] + from = "https://bud.js.org/packages/wordpress-hmr" + to = "https://bud.js.org/extensions/bud-preset-wordpress" + status = 301 + force = true + +[[redirects]] + from = "https://bud.js.org/guides/*" + to = "https://bud.js.org/learn/:splat" + status = 301 + force = true + +[[redirects]] + from = "https://bud.js.org/docs/bud.template" + to = "https://bud.js.org/reference/bud.html" + status = 301 + force = true + +[[redirects]] + from = "https://bud.js.org/docs/general-use/alternative-config-syntax" + to = "https://bud.js.org/learn/config/files/bud.config" + status = 301 + force = true + +[[redirects]] + from = "https://bud.js.org/docs/general-use/config-layers" + to = "https://bud.js.org/learn/config/files/bud.config" + status = 301 + force = true + +[[redirects]] + from = "https://bud.js.org/docs/general-use/extensions" + to = "https://bud.js.org/learn/config/extensions" + status = 301 + force = true + +[[redirects]] + from = "https://bud.js.org/docs/*" + to = "https://bud.js.org/reference/:splat" + status = 301 + force = true diff --git a/sources/@repo/docs/sidebars/docs.cjs b/sources/@repo/docs/sidebars/docs.cjs deleted file mode 100644 index 0bd4f3ae76..0000000000 --- a/sources/@repo/docs/sidebars/docs.cjs +++ /dev/null @@ -1,21 +0,0 @@ -module.exports = { - sidebar: [ - { - collapsed: false, - collapsible: false, - items: [ - { - dirName: `.`, - type: `autogenerated`, - }, - ], - label: `Configuration API`, - link: { - description: `Configuration API Reference`, - slug: `/config`, - type: `generated-index`, - }, - type: `category`, - }, - ], -} diff --git a/sources/@repo/docs/sidebars/guides.cjs b/sources/@repo/docs/sidebars/learn.cjs similarity index 50% rename from sources/@repo/docs/sidebars/guides.cjs rename to sources/@repo/docs/sidebars/learn.cjs index cc2910b54d..177481bcc8 100644 --- a/sources/@repo/docs/sidebars/guides.cjs +++ b/sources/@repo/docs/sidebars/learn.cjs @@ -1,20 +1,49 @@ module.exports = { sidebar: [ - `index`, - `create-bud-app`, { + collapsed: false, items: [ - `configure/bud.config.js`, - `configure/paths`, - `configure/assets`, - `configure/optimizing`, - `configure/extensions`, - `configure/editor-integration`, + `getting-started/index`, + `getting-started/create-bud-app`, + `getting-started/adding-typescript`, + `getting-started/adding-postcss`, + `getting-started/adding-sass`, + `getting-started/adding-react`, + `getting-started/adding-tailwindcss`, + `getting-started/adding-emotion`, + `getting-started/adding-eslint`, + `getting-started/adding-stylelint`, + `getting-started/adding-vue`, + `getting-started/adding-wordpress-support`, ], - label: `Project config`, + label: `Getting started`, + type: `category`, + }, + { + items: [ + { + items: [ + `config/files/bud.config`, + `config/files/tsconfig`, + `config/files/package`, + `config/files/env`, + ], + label: `Files`, + link: { + slug: `/config/files`, + type: `generated-index`, + }, + type: `category`, + }, + `config/paths`, + `config/entrypoints`, + `config/assets`, + `config/optimization`, + `config/server`, + ], + label: `Configuring bud.js`, link: { - description: `Get started configuring bud.js`, - slug: `/configure`, + slug: `/config`, type: `generated-index`, }, type: `category`, @@ -25,10 +54,10 @@ module.exports = { `modules/css-modules`, `modules/static-assets`, ], - label: `Modules`, + label: `Source modules`, link: { - description: `Using JS, CSS and static assets in your application code.`, - slug: `/guides/modules`, + description: `Learn about the features available to your application in the context of your source code.`, + slug: `/learn/modules`, type: `generated-index`, }, type: `category`, @@ -47,6 +76,7 @@ module.exports = { `cli/clean`, `cli/doctor`, `cli/repl`, + `cli/upgrade`, ], label: `CLI`, link: { @@ -57,17 +87,13 @@ module.exports = { }, { items: [ - `general-use/development-server`, `general-use/customizing-loaders`, `general-use/compiler-sources`, - `general-use/alternative-config-syntax`, - `general-use/config-layers`, - `general-use/extensions`, `general-use/multi-instance`, `general-use/node-api`, `general-use/esmodules`, + `general-use/extensions`, `general-use/remote-sources`, - `general-use/managing-dependencies`, `general-use/pnpm`, ], label: `Going deeper`, diff --git a/sources/@repo/docs/sidebars/reference.cjs b/sources/@repo/docs/sidebars/reference.cjs new file mode 100644 index 0000000000..94d21eeb31 --- /dev/null +++ b/sources/@repo/docs/sidebars/reference.cjs @@ -0,0 +1,8 @@ +module.exports = { + items: [ + { + dirName: `.`, + type: `autogenerated`, + }, + ], +} diff --git a/sources/@repo/docs/src/components/blockquote/blockquote.component.tsx b/sources/@repo/docs/src/components/blockquote/blockquote.component.tsx deleted file mode 100644 index a5d1ed93c2..0000000000 --- a/sources/@repo/docs/src/components/blockquote/blockquote.component.tsx +++ /dev/null @@ -1,14 +0,0 @@ -import React from 'react' - -export const Component = ({children, cite, src}) => { - return ( -
-

{children}

- - - — {cite} - - -
- ) -} diff --git a/sources/@repo/docs/src/components/blockquote/index.ts b/sources/@repo/docs/src/components/blockquote/index.ts deleted file mode 100644 index 738d009cc1..0000000000 --- a/sources/@repo/docs/src/components/blockquote/index.ts +++ /dev/null @@ -1 +0,0 @@ -export * as BlockQuote from './blockquote.component' diff --git a/sources/@repo/docs/src/components/card/index.tsx b/sources/@repo/docs/src/components/card/index.tsx deleted file mode 100644 index 5314c2c313..0000000000 --- a/sources/@repo/docs/src/components/card/index.tsx +++ /dev/null @@ -1,28 +0,0 @@ -import Link from '@docusaurus/Link' -import React from 'react' - -export const Card = ({description, links, title}) => ( -
-
-

{title}

-
- -
-

{description}

-
- -
-
- {links.map((link, id) => ( - - ))} -
-
-
-) diff --git a/sources/@repo/docs/src/components/features/index.module.css b/sources/@repo/docs/src/components/features/index.module.css deleted file mode 100644 index 52e81bf074..0000000000 --- a/sources/@repo/docs/src/components/features/index.module.css +++ /dev/null @@ -1,291 +0,0 @@ -.heroBanner { - padding: 6rem 3rem; - text-align: center; - position: relative; - overflow: hidden; - color: white; - background: linear-gradient(217deg, rgb(86, 98, 218), rgb(71, 83, 220)); -} - -@media screen and (max-width: 966px) { - .heroBanner { - padding: 3rem 2rem; - background: linear-gradient( - 217deg, - rgb(86, 98, 218), - rgb(71, 83, 220) - ); - } -} - -.section { - padding: 72px 0; -} - -.sectionAlt { - background-color: var(--ifm-color-emphasis-100); -} - -.sectionInner { - margin: 0 auto; -} - -.featureImage { - width: auto; - max-height: 128px; - margin: 0 auto; -} - -.featureHeading { - font-size: var(--ifm-h1-font-size); - padding-top: 1rem; -} - -.announcement { - font-weight: bold; - font-size: 24px; - padding: 48px; - margin: 0 auto; - text-align: center; -} - -.announcementInner { - margin: 0 auto; - max-width: 768px; -} - -.banner { - font-weight: bold; - font-size: 20px; - padding: 20px; - max-width: 768px; - margin: 0 auto; - text-align: center; -} - -.hero { - background-color: #2b3137; - padding: 48px; -} - -.heroInner { - margin: 0 auto; - max-width: 1100px; - padding: 0 20px; -} - -.heroProjectTagline { - color: #fff; - font-size: 60px; - margin: 0; -} - -.heroTitleTextHtml b { - color: var(--ifm-color-primary); -} - -@keyframes jack-in-the-box { - from { - opacity: 0; - transform: scale(0.1) rotate(30deg); - transform-origin: center bottom; - } - - 50% { - transform: rotate(-10deg); - } - - 70% { - transform: rotate(3deg); - } - - to { - opacity: 1; - transform: scale(1); - } -} - -.heroLogo { - animation-duration: 2s; - animation-name: jack-in-the-box; - float: right; - margin-top: 20px; - padding: 0 20px 20px; -} - -.indexCtas { - --ifm-button-size-multiplier: 1.6; - display: flex; - flex-wrap: wrap; - align-items: center; - margin-top: 24px; -} - -.indexCtas a, -.indexCtas a:hover { - color: black; -} - -.indexCtas a:last-of-type { - margin: 20px 36px; -} - -.indexCtasGitHubButtonWrapper { - display: flex; -} - -.indexCtasGitHubButton { - overflow: hidden; -} - -.indexCtaTryNowButton:hover { - color: var(--ifm-color-primary); -} - -@media only screen and (max-width: 768px) { - .hero { - padding-left: 20px; - padding-right: 20px; - } - - .heroInner { - padding: 0; - } - - .heroProjectTagline { - font-size: 36px; - text-align: center; - } - - .heroLogo { - display: block; - float: none; - margin: 0 auto; - } - - .indexCtas { - justify-content: center; - } - - .indexCtas a { - margin: 20px 36px; - } - - .indexCtasGitHubButton { - display: none; - } -} - -.testimonialsSection { - margin-top: -2rem; -} - -.testimonialsSection > :global(.col) { - padding-top: 2rem; - margin-top: -2rem; -} - -.testimonialsSection > :global(.col) > * { - margin-top: 2rem; -} - -/* Used to test CSS insertion order */ -.test-marker-site-index-page { - content: 'site-index-page'; -} - -.buttons { - display: flex; - align-items: center; - justify-content: center; - padding: 3rem 1rem; -} - -.buttons a { - border: 1px solid white; - border-radius: 3px; - color: white; - margin-left: 0.5rem; - margin-right: 0.5rem; -} - -.buttons a:hover { - background: white; - color: var(--ifm-color-primary-dark); -} - -.features { - display: flex; - align-items: center; - padding: 4rem; - width: 100%; -} - -.featureSvg { - height: 200px; - width: 200px; -} - -.comparison { - width: 100%; - margin: 0; - padding: 0; -} - -.comparison table { - margin-left: auto; - margin-right: auto; - width: 100%; - display: inline-table; -} - -.comparison table thead { - background-color: transparent; - border: none; -} - -.comparison table th { - background-color: transparent; - color: var(--ifm-table-head-color); - font-weight: var(--ifm-table-head-font-weight); - text-align: left; - border: none; -} - -.comparison table th:not(:first-child) { - text-align: center; -} - -.comparison table thead tr { - border-bottom: none; - border-top: none; -} - -.comparison table tr { - background-color: transparent; -} - -.comparison table td { - border: none; -} - -.comparison table td:not(:first-child) { - text-align: center; - max-width: 10vw; - width: 10vw; -} - -.comparison .success { - background: rgba(38, 178, 38, 0.2); - border: 1px solid white !important; -} - -.comparison .error { - background: rgba(178, 38, 38, 0.2); - border: 1px solid white !important; -} - -.comparison .warning { - background: rgba(255, 162, 0, 0.2); - border: 1px solid white !important; -} diff --git a/sources/@repo/docs/src/components/features/index.tsx b/sources/@repo/docs/src/components/features/index.tsx deleted file mode 100644 index 4337a9ac19..0000000000 --- a/sources/@repo/docs/src/components/features/index.tsx +++ /dev/null @@ -1,26 +0,0 @@ -// @ts-ignore -import Comparison from '@site/content/guides/comparison.mdx' -import clsx from 'clsx' -import React, {useEffect} from 'react' - -import styles from './index.module.css' - -export const Features = () => { - useEffect(() => { - document.querySelectorAll(`table td`).forEach(td => { - if (td.textContent == `✅`) td.classList.add(styles.success) - if (td.textContent == `❌`) td.classList.add(styles.error) - if (td.textContent == `partial`) td.classList.add(styles.warning) - }) - }, []) - - return ( -
-
-
- -
-
-
- ) -} diff --git a/sources/@repo/docs/src/components/mast/index.module.css b/sources/@repo/docs/src/components/mast/index.module.css index 52e81bf074..a2b12ec46b 100644 --- a/sources/@repo/docs/src/components/mast/index.module.css +++ b/sources/@repo/docs/src/components/mast/index.module.css @@ -1,59 +1,28 @@ +[dark-mode] .heroBanner { + color: white; +} + .heroBanner { - padding: 6rem 3rem; + padding: 8rem 3rem 6rem 3rem; text-align: center; position: relative; overflow: hidden; - color: white; - background: linear-gradient(217deg, rgb(86, 98, 218), rgb(71, 83, 220)); +} + +.heroBanner > div { + max-width: 900px; } @media screen and (max-width: 966px) { .heroBanner { padding: 3rem 2rem; - background: linear-gradient( - 217deg, - rgb(86, 98, 218), - rgb(71, 83, 220) - ); } } -.section { - padding: 72px 0; -} - .sectionAlt { background-color: var(--ifm-color-emphasis-100); } -.sectionInner { - margin: 0 auto; -} - -.featureImage { - width: auto; - max-height: 128px; - margin: 0 auto; -} - -.featureHeading { - font-size: var(--ifm-h1-font-size); - padding-top: 1rem; -} - -.announcement { - font-weight: bold; - font-size: 24px; - padding: 48px; - margin: 0 auto; - text-align: center; -} - -.announcementInner { - margin: 0 auto; - max-width: 768px; -} - .banner { font-weight: bold; font-size: 20px; diff --git a/sources/@repo/docs/src/components/mast/index.tsx b/sources/@repo/docs/src/components/mast/index.tsx deleted file mode 100644 index 1372d37c11..0000000000 --- a/sources/@repo/docs/src/components/mast/index.tsx +++ /dev/null @@ -1,30 +0,0 @@ -import Link from '@docusaurus/Link' -import clsx from 'clsx' -import React from 'react' - -import styles from './index.module.css' - -export const Mast = () => { - return ( -
-
-

- Bud is a beautiful way to build your CSS and JS -

-

- With support for Babel, React, PostCSS, CSS-in-JS, Sass, - Typescript, esbuild, ESLint, Prettier, and more. -

- -
- - Get started{` `}→ - -
-
-
- ) -} diff --git a/sources/@repo/docs/src/components/sponsors/sponsors.module.css b/sources/@repo/docs/src/components/sponsors/sponsors.module.css index 0fd2d04cfa..d085401b40 100644 --- a/sources/@repo/docs/src/components/sponsors/sponsors.module.css +++ b/sources/@repo/docs/src/components/sponsors/sponsors.module.css @@ -1,17 +1,5 @@ -.sponsors { - display: flex; - flex-wrap: wrap; - flex-direction: row; - align-items: align; - justify-content: center; - gap: 1.5rem; - padding: 0; - margin: 1.5rem; - padding-bottom: 36px; -} - .section { - padding: 36px 0; + padding: 4rem 0 1rem 0; display: block; text-align: center; } @@ -24,3 +12,20 @@ max-height: 120px; border-radius: var(--ifm-card-border-radius); } + +.sponsors { + display: flex; + flex-wrap: wrap; + flex-direction: row; + align-items: center; + justify-content: center; + gap: 1.5rem; + padding: 0; + margin: 1.5rem; + padding-bottom: 36px; +} + +.sponsors a { + height: 160px; + width: 160px; +} diff --git a/sources/@repo/docs/src/css/custom.css b/sources/@repo/docs/src/css/custom.css index f184eeabe4..5414ca123a 100644 --- a/sources/@repo/docs/src/css/custom.css +++ b/sources/@repo/docs/src/css/custom.css @@ -15,10 +15,10 @@ --ifm-font-family-base: 'Public Sans', system-ui, sans-serif; --ifm-font-family-monospace: 'dm', monospace; +} - --icon-external: url("data:image/svg+xml;charset=UTF-8,%3csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' style='stroke: rgb(82, 93, 220)' viewBox='0 0 16 16' %3E%3Cpath fill-rule='evenodd' d='M8.636 3.5a.5.5 0 0 0-.5-.5H1.5A1.5 1.5 0 0 0 0 4.5v10A1.5 1.5 0 0 0 1.5 16h10a1.5 1.5 0 0 0 1.5-1.5V7.864a.5.5 0 0 0-1 0V14.5a.5.5 0 0 1-.5.5h-10a.5.5 0 0 1-.5-.5v-10a.5.5 0 0 1 .5-.5h6.636a.5.5 0 0 0 .5-.5z'/%3E%3Cpath fill-rule='evenodd' d='M16 .5a.5.5 0 0 0-.5-.5h-5a.5.5 0 0 0 0 1h3.793L6.146 9.146a.5.5 0 1 0 .708.708L15 1.707V5.5a.5.5 0 0 0 1 0v-5z'/%3E%3C/svg%3E"); - --icon-code: url("data:image/svg+xml;charset=UTF-8,%3csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' style='stroke: rgb(82, 93, 220)' viewBox='0 0 24 24' stroke-width='2' %3E%3Cpath stroke-linecap='round' stroke-linejoin='round' d='M10 20l4-16m4 4l4 4-4 4M6 16l-4-4 4-4' /%3E%3C/svg%3E"); - --icon-cog: url("data:image/svg+xml;charset=UTF-8,%3csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' style='stroke: rgb(82, 93, 220)' viewBox='0 0 24 24' class='w-6 h-6' fill='none' stroke-width='2'%3e%3cpath stroke-linecap='round' stroke-linejoin='round' d='M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z' /%3e%3cpath stroke-linecap='round' stroke-linejoin='round' d='M15 12a3 3 0 11-6 0 3 3 0 016 0z' /%3e%3c/svg%3e"); +.navbar { + box-shadow: none; } article[itemprop='blogPost'] header > h1[itemprop='headline'] { @@ -29,6 +29,10 @@ article[itemprop='blogPost'] header > h1[itemprop='headline'] { --ifm-h2-font-size: 1.8rem; } +.theme-doc-sidebar-container { + border-right: none !important; +} + .alert--info { --ifm-alert-border-color: rgba(82, 93, 220, 0.5); --ifm-code-background: rgba(82, 93, 220, 0.1); @@ -38,30 +42,9 @@ article[itemprop='blogPost'] header > h1[itemprop='headline'] { --ifm-link-color: rgba(82, 93, 220, 0.8); } -.announcement .navbar__items--right > :last-child { - padding-left: var(--ifm-navbar-item-padding-horizontal); -} - -.card { - border: 1px solid rgba(206, 209, 247, 0.4); - box-shadow: none; -} - -.docusaurus-highlight-code-line { - background: rgba(140, 146, 220, 0.3); - display: block; - margin: 0 calc(-1 * var(--ifm-pre-padding)); - padding: 0 var(--ifm-pre-padding); -} - -.navbar__search-input { - border-radius: 5px; -} - .footer { - background: var(--ifm-color-primary-darker); + background: var(--ifm-background-surface-color); } - .markdown :not(button) a { color: var(--ifm-link-color); font-weight: bold; @@ -98,24 +81,40 @@ article[itemprop='blogPost'] header > h1[itemprop='headline'] { } } -/* Announcement Bar */ -div[class^='announcementBar_'] { - background-color: var(--ifm-color-primary-light); - color: white !important; +.navbar__link { + display: inline-block; } -*[class^='announcementBar'] button { - background-color: transparent; - color: white !important; +.navbar__link svg { + display: none; } -div[class^='announcementBar'] a { - color: white; - border-bottom: 1px solid white; - text-decoration: none; +.header-github-link, +.header-discourse-link { + content: ''; +} +.header-github-link:before, +.header-discourse-link:before { + content: ''; + display: flex; + height: 24px; + width: 24px; } -div[class^='announcement'] a:hover { - color: white; - text-decoration: underline; +.header-github-link:before { + background: url("data:image/svg+xml;charset=utf-8,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E") + no-repeat; +} +[data-theme='dark'] .header-github-link:before { + background: url("data:image/svg+xml;charset=utf-8,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill='white' d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E") + no-repeat; +} + +.header-discourse-link:before { + background: url("data:image/svg+xml,%3Csvg width='24' height='25' viewBox='0 0 24 25' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cg clip-path='url(%23clip0_1_4)'%3E%3Cpath d='M12.0862 0C5.52466 0 0 5.31961 0 11.8835V24.1887L12.0839 24.1771C18.6454 24.1771 23.9674 18.6524 23.9674 12.0909C23.9674 5.52932 18.6408 0 12.0862 0Z' fill='%23231F20'/%3E%3Cpath d='M12.2027 4.59961C10.927 4.60036 9.67328 4.93236 8.56436 5.5631C7.45545 6.19385 6.52931 7.10172 5.87661 8.19786C5.2239 9.29399 4.86701 10.5408 4.84085 11.8163C4.81469 13.0918 5.12017 14.3522 5.72738 15.4742L4.39456 19.7616L9.18058 18.6804C10.1821 19.1316 11.2718 19.3531 12.37 19.3287C13.4681 19.3042 14.5469 19.0345 15.5274 18.5392C16.5078 18.0439 17.365 17.3355 18.0363 16.466C18.7075 15.5966 19.1758 14.588 19.4068 13.5141C19.6378 12.4402 19.6257 11.3283 19.3714 10.2597C19.1171 9.1911 18.627 8.19292 17.937 7.33826C17.2469 6.48359 16.3745 5.79408 15.3835 5.32022C14.3926 4.84636 13.3081 4.60014 12.2097 4.59961H12.2027Z' fill='white'/%3E%3C/g%3E%3Cdefs%3E%3CclipPath id='clip0_1_4'%3E%3Crect width='24' height='24.233' fill='white'/%3E%3C/clipPath%3E%3C/defs%3E%3C/svg%3E%0A") + no-repeat; +} +[data-theme='dark'] .header-discourse-link:before { + background: url("data:image/svg+xml,%3Csvg width='24' height='25' viewBox='0 0 24 25' fill='currentColor' xmlns='http://www.w3.org/2000/svg'%3E%3Cg clip-path='url(%23clip0_1_4)'%3E%3Cpath d='M12.0862 0C5.52466 0 0 5.31961 0 11.8835V24.1887L12.0839 24.1771C18.6454 24.1771 23.9674 18.6524 23.9674 12.0909C23.9674 5.52932 18.6408 0 12.0862 0Z' fill='white'/%3E%3Cpath d='M12.2027 4.59961C10.927 4.60036 9.67328 4.93236 8.56436 5.5631C7.45545 6.19385 6.52931 7.10172 5.87661 8.19786C5.2239 9.29399 4.86701 10.5408 4.84085 11.8163C4.81469 13.0918 5.12017 14.3522 5.72738 15.4742L4.39456 19.7616L9.18058 18.6804C10.1821 19.1316 11.2718 19.3531 12.37 19.3287C13.4681 19.3042 14.5469 19.0345 15.5274 18.5392C16.5078 18.0439 17.365 17.3355 18.0363 16.466C18.7075 15.5966 19.1758 14.588 19.4068 13.5141C19.6378 12.4402 19.6257 11.3283 19.3714 10.2597C19.1171 9.1911 18.627 8.19292 17.937 7.33826C17.2469 6.48359 16.3745 5.79408 15.3835 5.32022C14.3926 4.84636 13.3081 4.60014 12.2097 4.59961H12.2027Z' fill='%23231F20'/%3E%3C/g%3E%3Cdefs%3E%3CclipPath id='clip0_1_4'%3E%3Crect width='24' height='24.233' fill='white'/%3E%3C/clipPath%3E%3C/defs%3E%3C/svg%3E%0A") + no-repeat; } diff --git a/sources/@repo/docs/src/theme/BlogTagsPostsPage/index.js b/sources/@repo/docs/src/theme/BlogTagsPostsPage/index.js index 051d07f6fa..bb38c5a24c 100644 --- a/sources/@repo/docs/src/theme/BlogTagsPostsPage/index.js +++ b/sources/@repo/docs/src/theme/BlogTagsPostsPage/index.js @@ -56,7 +56,7 @@ function BlogTagsPostsPageContent({items, listMetadata, sidebar, tag}) {
{tag.label?.match(/\d*.\d*/) ? ( - + ) : (

{title}

)} diff --git a/sources/@repo/markdown-kit/cli-examples/index.ts b/sources/@repo/markdown-kit/cli-examples/index.ts index 42ba8cc531..b4e845ebc2 100644 --- a/sources/@repo/markdown-kit/cli-examples/index.ts +++ b/sources/@repo/markdown-kit/cli-examples/index.ts @@ -6,13 +6,14 @@ import stripAnsi from 'strip-ansi' const main = async () => { await Promise.all([ generateMarkdown([`--help`]), - generateMarkdown([`dev`, `--help`]), - generateMarkdown([`doctor`, `--help`]), - generateMarkdown([`clean`, `--help`]), generateMarkdown([`build`, `--help`]), generateMarkdown([`build`, `production`, `--help`]), generateMarkdown([`build`, `development`, `--help`]), + generateMarkdown([`clean`, `--help`]), + generateMarkdown([`dev`, `--help`]), + generateMarkdown([`doctor`, `--help`]), generateMarkdown([`repl`, `--help`]), + generateMarkdown([`upgrade`, `--help`]), generateMarkdown([`view`, `--help`]), ]) } diff --git a/sources/@repo/markdown-kit/releases/data.ts b/sources/@repo/markdown-kit/releases/data.ts index 157ba0a0ce..613653c0f4 100644 --- a/sources/@repo/markdown-kit/releases/data.ts +++ b/sources/@repo/markdown-kit/releases/data.ts @@ -1,3 +1,5 @@ +import {path} from '@repo/constants' +import fs from 'fs-jetpack' import {Octokit} from 'octokit' interface ghRelease { @@ -82,7 +84,28 @@ if (!request?.data) { throw error } } -if (!releases) releases = request?.data?.filter(filter).map(parse) + +if (!releases) { + releases = request?.data + ?.filter(filter) + .map(parse) + .sort((a, b) => { + if (a.major > b.major) return -1 + if (a.major < b.major) return 1 + return 0 + }) + .sort((a, b) => { + if (a.minor > b.minor) return -1 + if (a.minor < b.minor) return 1 + return 0 + }) + + await fs.writeAsync( + path(`sources/@repo/docs/generated/releases/data.json`), + releases, + {jsonIndent: 2}, + ) +} export {releases} export type {release} diff --git a/sources/@repo/yarn-plugin-bud/bundles/@yarnpkg/plugin-bud.js b/sources/@repo/yarn-plugin-bud/bundles/@yarnpkg/plugin-bud.js index 0224d10086..976bbaffc0 100644 --- a/sources/@repo/yarn-plugin-bud/bundles/@yarnpkg/plugin-bud.js +++ b/sources/@repo/yarn-plugin-bud/bundles/@yarnpkg/plugin-bud.js @@ -15,7 +15,7 @@ globstar while`,e,p,r,f,w),this.matchOne(e.slice(p),r.slice(f),s))return this.de |_.__/ \\__._|\\__._| `),Object.values(Dt).filter(e=>e.usage).forEach(e=>{var r;(r=e.usage.examples)==null||r.forEach(([s,n])=>{process.stdout.write(` \x1B[34m${n}\x1B[0m ${s} -`)})})}};qt.paths=[["@bud"]];var ue=te(Rs());var mt=class extends R{constructor(){super(...arguments);this.tsconfig=P("config/tsconfig.json")}async bundle({alias:r={},external:s=[],format:n="esm",outdir:i,outfile:o,source:a}){return this.cli.run(["esbuild","--alias:webpack=@roots/bud-support/webpack","--allow-overwrite","--bundle","--external:crypto","--external:module","--external:node:*","--external:@roots/*","--minify","--log-level=warning","--platform=node",...Object.entries(r).map(([c,u])=>`--alias:${c}=${u}`),...s.map(c=>`--external:${c}`),`--format=${n}`,o?`--outfile=${o}`:null,i?`--outdir=${i}`:null,a].filter(Boolean))}async execute(){if(await Promise.all([this.bundle({format:"cjs",outfile:"sources/@roots/filesystem/vendor/sdk/index.cjs",source:"node_modules/@aws-sdk/client-s3/dist-es/index.js"}),this.bundle({format:"esm",outfile:"sources/@roots/bud-support/vendor/highlight/index.js",source:"sources/@roots/bud-support/src/highlight/index.ts"}).then(async()=>{await ue.writeAsync(P("sources/@roots/bud-support/vendor/highlight/index.d.ts"),"export declare const highlight: (code: string) => string;")}),this.bundle({external:["./runtime/getUrl.js"],format:"cjs",outfile:P("sources/@roots/bud-support/vendor/html-loader/index.cjs"),source:P("node_modules/html-loader/dist/index.js")}).then(async()=>{let s=P("sources/@roots/bud-support/vendor/html-loader/index.cjs"),n=await ue.readAsync(s);await ue.writeAsync(s,n.replace(/\.\/runtime\/getUrl\.js/g,"./runtime/getUrl.cjs")),await ue.copyAsync(P("node_modules/html-loader/dist/runtime/getUrl.js"),P("sources/@roots/bud-support/vendor/html-loader/runtime/getUrl.cjs"),{overwrite:!0})}),this.bundle({external:["./lib/loader.js"],format:"cjs",outfile:"sources/@roots/bud-support/vendor/html-webpack-plugin/index.cjs",source:"node_modules/html-webpack-plugin/index.js"}).then(async()=>{let s=P("sources/@roots/bud-support/vendor/html-webpack-plugin/index.cjs"),n=await ue.readAsync(s);await ue.writeAsync(s,n.replace(/\.\/lib\/loader\.js/g,"./lib/loader.cjs"))}),ue.copyAsync(P("node_modules/html-webpack-plugin/lib/loader.js"),P("sources/@roots/bud-support/vendor/html-webpack-plugin/lib/loader.cjs"),{overwrite:!0}),ue.copyAsync(P("node_modules/html-webpack-plugin/typings.d.ts"),P("sources/@roots/bud-support/vendor/html-webpack-plugin/index.d.cts"),{overwrite:!0})]).catch(s=>{throw s}),await this.cli.run(["@bud","tsc","--build",this.tsconfig,"--force"]).catch(s=>{throw s})!==0)throw new Error("Build failed")}};mt.paths=[["@bud","build"]],mt.usage={category:"@bud",description:"Build packages",examples:[["build packages","yarn @bud build"]]};var gt=class extends R{async execute(){await this.cli.run(["exec","git","clean","-fxd"])}};gt.paths=[["@bud","clean"]],gt.usage={category:"@bud",description:"clean project artifacts",examples:[["clean project artifacts","yarn @bud clean"]]};var yt=class extends R{async execute(){await this.cli.run(["workspace","@repo/yarn-plugin-bud","build"]).catch(e=>{throw e}).then(e=>{if(e!==0)throw new Error("Plugin could not be built.")})}};yt.paths=[["@bud","plugin","build"]],yt.usage={category:"@bud",examples:[["build @bud yarn plugin","yarn @bud plugin build"]]};var _t=class extends R{async execute(){await this.cli.run(["workspace","@repo/markdown-kit","exec","node","contributors/index.js"]).catch(e=>{throw e})}};_t.paths=[["@bud","contributors"]],_t.usage={category:"@bud",description:"Aggregate contributor data",examples:[["update contributors","yarn @bud contributors"]]};var bt=class extends R{async execute(){await this.cli.run(["@bud","build"]),await this.cli.run(["@bud","docs","build"]),this.promised.push(this.cli.run(["@bud","tsc","--watch"]),this.cli.run(["@bud","test","unit"]),this.cli.run(["@bud","docs","dev"])),await Promise.all(this.promised)}};bt.paths=[["@bud","dev"]],bt.usage={category:"@bud",description:"develop project code",examples:[["run tsc, docusaurus & vitest in watch mode","yarn @bud dev"]]};var St=class extends R{async execute(){await this.cli.run(["@bud","build"]).then(e=>e!==0&&this.catch(new Error(`\`@bud build\` returned error code ${e}`))).catch(this.catch),await this.cli.run(["workspace","@repo/markdown-kit","run","build"]).then(e=>e!==0&&this.catch(new Error(`\`workspace @repo/markdown-kit run build\` returned error code ${e}`))).catch(this.catch),await Promise.all([this.cli.run(["workspace","@repo/markdown-kit","exec","node","compiled/cli-examples/index.js"]).catch(this.catch),this.cli.run(["workspace","@repo/markdown-kit","exec","node","compiled/releases/index.js"]).catch(this.catch),this.cli.run(["workspace","@repo/markdown-kit","exec","node","compiled/readme/index.js"]).catch(this.catch)]),await this.cli.run(["@bud","docusaurus","build"]).then(e=>e!==0&&this.catch(new Error(`\`@bud docusaurus build\` returned error code ${e}`))).catch(this.catch)}};St.paths=[["@bud","docs"]],St.usage={category:"@bud",description:"build docs and other markdown files",examples:[["build docs and readme","yarn @bud docs"]]};var Et=class extends R{async execute(){await this.cli.run(["@bud","docs","build"]),await this.cli.run(["@bud","docusaurus","start"])}};Et.paths=[["@bud","docs","dev"]],Et.usage={category:"@bud",description:"develop docs",examples:[["develop docs","yarn @bud docs dev"]]};var vt=class extends R{async execute(){this.promised.push(this.cli.run(["@bud","eslint"]).then(this.throwIfError).catch(this.catch),this.cli.run(["@bud","syncpack"]).then(this.throwIfError).catch(this.catch),this.cli.run(["@bud","prettier"]).then(this.throwIfError).catch(this.catch),this.cli.run(["@bud","package-check"]).then(this.throwIfError).catch(this.catch)),await Promise.all(this.promised)}};vt.paths=[["@bud","lint"]],vt.usage={category:"@bud",description:"Lint project"};var we=te(Rs());var wt=class extends R{async execute(){if(await we.removeAsync(P("storage/mocks")).catch(this.catch),await we.removeAsync(P("storage","packages")).catch(this.catch),await we.existsAsync(P("storage",".verdaccio-db.json"))){let r=await we.readAsync(P("storage",".verdaccio-db.json"),"json").catch(this.catch);r.list=[],await we.writeAsync(P("storage/.verdaccio-db.json"),r).catch(this.catch)}}};wt.paths=[["@bud","registry","clean"]],wt.usage={category:"@bud",description:"clean previously published packages",examples:[["clean previously published packages","yarn @bud registry clean"]]};var xt=class extends R{async execute(){try{await this.cli.run(["@bud","pm2","start",P("node_modules","verdaccio","build","lib","cli","cli.js"),"-n","verdaccio","--","--config",P("config","verdaccio","config.yaml")])}catch{}try{await this.cli.run(["@bud","pm2","save"])}catch{}}};xt.paths=[["@bud","registry","start"]],xt.usage={category:"@bud",description:"start verdaccio registry",examples:[["start verdaccio server","yarn @bud registry start"]]};var At=class extends R{async execute(){try{await this.cli.run(["@bud","pm2","stop","verdaccio"]),await this.cli.run(["@bud","pm2","delete","verdaccio"])}catch{}}};At.paths=[["@bud","registry","stop"]],At.usage={category:"@bud",description:"stop verdaccio registry",examples:[["stop verdaccio server","yarn @bud registry stop"]]};var Ps=E("clipanion");var Ct=class extends R{constructor(){super(...arguments);this.registry=Ps.Option.String("-r,--registry","http://localhost:4873",{description:"Release registry"});this.tag=Ps.Option.String("-t,--tag",{description:"Release tag",required:!0});this.version=Ps.Option.String("-v,--version",{description:"Release version",required:!1})}async catch(r){throw await this.resetRegistry(),r}async execute(){if(this.registry.startsWith("http://localhost:4873")&&(await this.cli.run(["config","set","npmPublishRegistry","http://localhost:4873"]).then(this.throwIfError).catch(this.catch),await this.cli.run(["config","set","npmRegistryServer","http://localhost:4873"]).then(this.throwIfError).catch(this.catch)),!this.version){let r=new Date,s=`${r.getUTCFullYear()}.${r.getUTCMonth()+1}.${r.getUTCDate()}`;await this.cli.run(["exec","npm","show",`@roots/bud@${s}`,"--tag",this.tag,"--registry",this.registry]).then(()=>{this.version=`${s}-${r.getUTCHours()}${r.getUTCMinutes()}`}).catch(()=>{this.version=s})}await this.cli.run(["@bud","version",this.version]).then(this.throwIfError).catch(this.catch),await this.cli.run(["workspaces","foreach","--no-private","npm","publish","--access","public","--tag",this.tag]).then(this.throwIfError).catch(this.catch),await this.resetRegistry()}async resetRegistry(){await this.cli.run(["config","set","npmPublishRegistry","https://registry.npmjs.org"]).catch(r=>{}),await this.cli.run(["config","set","npmRegistryServer","https://registry.npmjs.org"]).catch(r=>{}),await this.cli.run(["@bud","version","0.0.0"]).catch(r=>{}),await this.cli.run(["install"]).catch(r=>{})}};Ct.paths=[["@bud","release"]],Ct.usage={category:"@bud",description:"Do a release.",examples:[["Bump packages to x.y.z and publish","yarn @bud release --version x.y.z --tag latest"]]};var to=E("clipanion"),Bf=te(Rs());var Rt=class extends R{constructor(){super(...arguments);this.configuration=to.Option.String({required:!0});this.passthrough=to.Option.Proxy({name:"vitest passthrough options"})}async execute(){let r=["@bud","vitest"];return["e2e","integration"].includes(this.configuration)&&(r.push("--run"),await Bf.removeAsync(P("storage","mocks")).catch(s=>{throw s}),await this.cli.run(["@bud","release","--tag","latest","--registry","http://localhost:4873/"]).catch(s=>{throw s})),!r.includes("--config")&&r.push("--config",P("config",`vitest.${this.configuration}.config.ts`)),r.push(...this.passthrough),await this.cli.run(r)}};Rt.paths=[["@bud","test"]],Rt.usage={category:"@bud",description:"run test suites",examples:[["run unit test suite","yarn @bud test unit"],["run integration test suite","yarn @bud test integration"],["run e2e test suite","yarn @bud test e2e"]]};var Gf=E("clipanion");var Pt=class extends R{constructor(){super(...arguments);this.version=Gf.Option.String()}async execute(){await this.cli.run(["workspaces","foreach","--no-private","package","set","version",this.version]).then(this.throwIfError).catch(this.catch)}};Pt.paths=[["@bud","version"]],Pt.usage={category:"@bud",description:"bump version of public packages",examples:[["Bump packages to x.y.z","yarn @bud version x.y.z"]]};var Wt=E("@yarnpkg/shell"),Uf=async()=>{await(0,Wt.execute)("yarn",["@bud","plugin","build"]),await(0,Wt.execute)("yarn",["@bud","registry","start"]),await(0,Wt.execute)("yarn",["@bud","build"]),await(0,Wt.execute)("yarn",["@bud"])};var M_={commands:Object.values(Dt),hooks:{afterAllInstalled:Uf}},F_=M_;return Zf(H_);})(); +`)})})}};qt.paths=[["@bud"]];var ue=te(Rs());var mt=class extends R{constructor(){super(...arguments);this.tsconfig=P("config/tsconfig.json")}async bundle({alias:r={},external:s=[],format:n="esm",outdir:i,outfile:o,source:a}){return this.cli.run(["esbuild","--alias:webpack=@roots/bud-support/webpack","--allow-overwrite","--bundle","--external:crypto","--external:module","--external:node:*","--external:@roots/*","--minify","--log-level=warning","--platform=node",...Object.entries(r).map(([c,u])=>`--alias:${c}=${u}`),...s.map(c=>`--external:${c}`),`--format=${n}`,o?`--outfile=${o}`:null,i?`--outdir=${i}`:null,a].filter(Boolean))}async execute(){if(await Promise.all([this.bundle({format:"cjs",outfile:"sources/@roots/filesystem/vendor/sdk/index.cjs",source:"node_modules/@aws-sdk/client-s3/dist-es/index.js"}),this.bundle({format:"esm",outfile:"sources/@roots/bud-support/vendor/highlight/index.js",source:"sources/@roots/bud-support/src/highlight/index.ts"}).then(async()=>{await ue.writeAsync(P("sources/@roots/bud-support/vendor/highlight/index.d.ts"),"export declare const highlight: (code: string) => string;")}),this.bundle({external:["./runtime/getUrl.js"],format:"cjs",outfile:P("sources/@roots/bud-support/vendor/html-loader/index.cjs"),source:P("node_modules/html-loader/dist/index.js")}).then(async()=>{let s=P("sources/@roots/bud-support/vendor/html-loader/index.cjs"),n=await ue.readAsync(s);await ue.writeAsync(s,n.replace(/\.\/runtime\/getUrl\.js/g,"./runtime/getUrl.cjs")),await ue.copyAsync(P("node_modules/html-loader/dist/runtime/getUrl.js"),P("sources/@roots/bud-support/vendor/html-loader/runtime/getUrl.cjs"),{overwrite:!0})}),this.bundle({external:["./lib/loader.js"],format:"cjs",outfile:"sources/@roots/bud-support/vendor/html-webpack-plugin/index.cjs",source:"node_modules/html-webpack-plugin/index.js"}).then(async()=>{let s=P("sources/@roots/bud-support/vendor/html-webpack-plugin/index.cjs"),n=await ue.readAsync(s);await ue.writeAsync(s,n.replace(/\.\/lib\/loader\.js/g,"./lib/loader.cjs"))}),ue.copyAsync(P("node_modules/html-webpack-plugin/lib/loader.js"),P("sources/@roots/bud-support/vendor/html-webpack-plugin/lib/loader.cjs"),{overwrite:!0}),ue.copyAsync(P("node_modules/html-webpack-plugin/typings.d.ts"),P("sources/@roots/bud-support/vendor/html-webpack-plugin/index.d.cts"),{overwrite:!0})]).catch(s=>{throw s}),await this.cli.run(["@bud","tsc","--build",this.tsconfig,"--force"]).catch(s=>{throw s})!==0)throw new Error("Build failed")}};mt.paths=[["@bud","build"]],mt.usage={category:"@bud",description:"Build packages",examples:[["build packages","yarn @bud build"]]};var gt=class extends R{async execute(){await this.cli.run(["exec","git","clean","-fxd"])}};gt.paths=[["@bud","clean"]],gt.usage={category:"@bud",description:"clean project artifacts",examples:[["clean project artifacts","yarn @bud clean"]]};var yt=class extends R{async execute(){await this.cli.run(["workspace","@repo/yarn-plugin-bud","build"]).catch(e=>{throw e}).then(e=>{if(e!==0)throw new Error("Plugin could not be built.")})}};yt.paths=[["@bud","plugin","build"]],yt.usage={category:"@bud",examples:[["build @bud yarn plugin","yarn @bud plugin build"]]};var _t=class extends R{async execute(){await this.cli.run(["workspace","@repo/markdown-kit","exec","node","contributors/index.js"]).catch(e=>{throw e})}};_t.paths=[["@bud","contributors"]],_t.usage={category:"@bud",description:"Aggregate contributor data",examples:[["update contributors","yarn @bud contributors"]]};var bt=class extends R{async execute(){await this.cli.run(["@bud","build"]),await this.cli.run(["@bud","docs","build"]),this.promised.push(this.cli.run(["@bud","tsc","--watch"]),this.cli.run(["@bud","test","unit"]),this.cli.run(["@bud","docs","dev"])),await Promise.all(this.promised)}};bt.paths=[["@bud","dev"]],bt.usage={category:"@bud",description:"develop project code",examples:[["run tsc, docusaurus & vitest in watch mode","yarn @bud dev"]]};var St=class extends R{async execute(){await this.cli.run(["@bud","build"]).then(e=>e!==0&&this.catch(new Error(`\`@bud build\` returned error code ${e}`))).catch(this.catch),await this.cli.run(["workspace","@repo/markdown-kit","run","build"]).then(e=>e!==0&&this.catch(new Error(`\`workspace @repo/markdown-kit run build\` returned error code ${e}`))).catch(this.catch),await Promise.all([this.cli.run(["workspace","@repo/markdown-kit","exec","node","compiled/cli-examples/index.js"]).catch(this.catch),this.cli.run(["workspace","@repo/markdown-kit","exec","node","compiled/releases/index.js"]).catch(this.catch),this.cli.run(["workspace","@repo/markdown-kit","exec","node","compiled/readme/index.js"]).catch(this.catch)]),await this.cli.run(["@bud","docusaurus","build"]).then(e=>e!==0&&this.catch(new Error(`\`@bud docusaurus build\` returned error code ${e}`))).catch(this.catch)}};St.paths=[["@bud","docs"],["@bud","docs","build"]],St.usage={category:"@bud",description:"build docs and other markdown files",examples:[["build docs and readme","yarn @bud docs"]]};var Et=class extends R{async execute(){await this.cli.run(["@bud","docs","build"]),await this.cli.run(["@bud","docusaurus","start"])}};Et.paths=[["@bud","docs","dev"]],Et.usage={category:"@bud",description:"develop docs",examples:[["develop docs","yarn @bud docs dev"]]};var vt=class extends R{async execute(){this.promised.push(this.cli.run(["@bud","eslint"]).then(this.throwIfError).catch(this.catch),this.cli.run(["@bud","syncpack"]).then(this.throwIfError).catch(this.catch),this.cli.run(["@bud","prettier"]).then(this.throwIfError).catch(this.catch),this.cli.run(["@bud","package-check"]).then(this.throwIfError).catch(this.catch)),await Promise.all(this.promised)}};vt.paths=[["@bud","lint"]],vt.usage={category:"@bud",description:"Lint project"};var we=te(Rs());var wt=class extends R{async execute(){if(await we.removeAsync(P("storage/mocks")).catch(this.catch),await we.removeAsync(P("storage","packages")).catch(this.catch),await we.existsAsync(P("storage",".verdaccio-db.json"))){let r=await we.readAsync(P("storage",".verdaccio-db.json"),"json").catch(this.catch);r.list=[],await we.writeAsync(P("storage/.verdaccio-db.json"),r).catch(this.catch)}}};wt.paths=[["@bud","registry","clean"]],wt.usage={category:"@bud",description:"clean previously published packages",examples:[["clean previously published packages","yarn @bud registry clean"]]};var xt=class extends R{async execute(){try{await this.cli.run(["@bud","pm2","start",P("node_modules","verdaccio","build","lib","cli","cli.js"),"-n","verdaccio","--","--config",P("config","verdaccio","config.yaml")])}catch{}try{await this.cli.run(["@bud","pm2","save"])}catch{}}};xt.paths=[["@bud","registry","start"]],xt.usage={category:"@bud",description:"start verdaccio registry",examples:[["start verdaccio server","yarn @bud registry start"]]};var At=class extends R{async execute(){try{await this.cli.run(["@bud","pm2","stop","verdaccio"]),await this.cli.run(["@bud","pm2","delete","verdaccio"])}catch{}}};At.paths=[["@bud","registry","stop"]],At.usage={category:"@bud",description:"stop verdaccio registry",examples:[["stop verdaccio server","yarn @bud registry stop"]]};var Ps=E("clipanion");var Ct=class extends R{constructor(){super(...arguments);this.registry=Ps.Option.String("-r,--registry","http://localhost:4873",{description:"Release registry"});this.tag=Ps.Option.String("-t,--tag",{description:"Release tag",required:!0});this.version=Ps.Option.String("-v,--version",{description:"Release version",required:!1})}async catch(r){throw await this.resetRegistry(),r}async execute(){if(this.registry.startsWith("http://localhost:4873")&&(await this.cli.run(["config","set","npmPublishRegistry","http://localhost:4873"]).then(this.throwIfError).catch(this.catch),await this.cli.run(["config","set","npmRegistryServer","http://localhost:4873"]).then(this.throwIfError).catch(this.catch)),!this.version){let r=new Date,s=`${r.getUTCFullYear()}.${r.getUTCMonth()+1}.${r.getUTCDate()}`;await this.cli.run(["exec","npm","show",`@roots/bud@${s}`,"--tag",this.tag,"--registry",this.registry]).then(()=>{this.version=`${s}-${r.getUTCHours()}${r.getUTCMinutes()}`}).catch(()=>{this.version=s})}await this.cli.run(["@bud","version",this.version]).then(this.throwIfError).catch(this.catch),await this.cli.run(["workspaces","foreach","--no-private","npm","publish","--access","public","--tag",this.tag]).then(this.throwIfError).catch(this.catch),await this.resetRegistry()}async resetRegistry(){await this.cli.run(["config","set","npmPublishRegistry","https://registry.npmjs.org"]).catch(r=>{}),await this.cli.run(["config","set","npmRegistryServer","https://registry.npmjs.org"]).catch(r=>{}),await this.cli.run(["@bud","version","0.0.0"]).catch(r=>{}),await this.cli.run(["install"]).catch(r=>{})}};Ct.paths=[["@bud","release"]],Ct.usage={category:"@bud",description:"Do a release.",examples:[["Bump packages to x.y.z and publish","yarn @bud release --version x.y.z --tag latest"]]};var to=E("clipanion"),Bf=te(Rs());var Rt=class extends R{constructor(){super(...arguments);this.configuration=to.Option.String({required:!0});this.passthrough=to.Option.Proxy({name:"vitest passthrough options"})}async execute(){let r=["@bud","vitest"];return["e2e","integration"].includes(this.configuration)&&(r.push("--run"),await Bf.removeAsync(P("storage","mocks")).catch(s=>{throw s}),await this.cli.run(["@bud","release","--tag","latest","--registry","http://localhost:4873/"]).catch(s=>{throw s})),!r.includes("--config")&&r.push("--config",P("config",`vitest.${this.configuration}.config.ts`)),r.push(...this.passthrough),await this.cli.run(r)}};Rt.paths=[["@bud","test"]],Rt.usage={category:"@bud",description:"run test suites",examples:[["run unit test suite","yarn @bud test unit"],["run integration test suite","yarn @bud test integration"],["run e2e test suite","yarn @bud test e2e"]]};var Gf=E("clipanion");var Pt=class extends R{constructor(){super(...arguments);this.version=Gf.Option.String()}async execute(){await this.cli.run(["workspaces","foreach","--no-private","package","set","version",this.version]).then(this.throwIfError).catch(this.catch)}};Pt.paths=[["@bud","version"]],Pt.usage={category:"@bud",description:"bump version of public packages",examples:[["Bump packages to x.y.z","yarn @bud version x.y.z"]]};var Wt=E("@yarnpkg/shell"),Uf=async()=>{await(0,Wt.execute)("yarn",["@bud","plugin","build"]),await(0,Wt.execute)("yarn",["@bud","registry","start"]),await(0,Wt.execute)("yarn",["@bud","build"]),await(0,Wt.execute)("yarn",["@bud"])};var M_={commands:Object.values(Dt),hooks:{afterAllInstalled:Uf}},F_=M_;return Zf(H_);})(); /*! * fill-range * diff --git a/sources/@repo/yarn-plugin-bud/sources/command/docs.build.ts b/sources/@repo/yarn-plugin-bud/sources/command/docs.build.ts index 2b99aafe30..9d7491c700 100644 --- a/sources/@repo/yarn-plugin-bud/sources/command/docs.build.ts +++ b/sources/@repo/yarn-plugin-bud/sources/command/docs.build.ts @@ -6,7 +6,10 @@ import {Command} from './base.command' * Docs command class */ export class Docs extends Command { - public static paths: CommandClass['paths'] = [[`@bud`, `docs`]] + public static paths: CommandClass['paths'] = [ + [`@bud`, `docs`], + [`@bud`, `docs`, `build`], + ] public static usage: CommandClass['usage'] = { category: `@bud`, diff --git a/sources/@roots/bud-api/docs/assets/related.md b/sources/@roots/bud-api/docs/assets/related.md index 324e50077d..9a2bae5c05 100644 --- a/sources/@roots/bud-api/docs/assets/related.md +++ b/sources/@roots/bud-api/docs/assets/related.md @@ -1,4 +1,4 @@ ## Related -- [bud.copyFile](/docs/bud.copyFile) -- [bud.copyDir](/docs/bud.copyDir) +- [bud.copyFile](/reference/bud.copyFile) +- [bud.copyDir](/reference/bud.copyDir) diff --git a/sources/@roots/bud-api/docs/define/usage.md b/sources/@roots/bud-api/docs/define/usage.md index 998f5893fa..dca18b5151 100644 --- a/sources/@roots/bud-api/docs/define/usage.md +++ b/sources/@roots/bud-api/docs/define/usage.md @@ -16,7 +16,7 @@ Any instances of `APP_NAME` in your application code will be replaced with `My A console.log(APP_NAME) ``` -Replacements will also be made when compiling [html templates](/docs/bud.html). +Replacements will also be made when compiling [html templates](/reference/bud.html). ```html title='public/index.html' diff --git a/sources/@roots/bud-api/docs/entry/globbing.md b/sources/@roots/bud-api/docs/entry/globbing.md index 1e7f092b3e..5ed5935585 100644 --- a/sources/@roots/bud-api/docs/entry/globbing.md +++ b/sources/@roots/bud-api/docs/entry/globbing.md @@ -2,7 +2,7 @@ title: Globbing --- -**bud.entry** can be used with [bud.glob](/docs/bud.glob) to find matching files. +**bud.entry** can be used with [bud.glob](/reference/bud.glob) to find matching files. ```js title='bud.config.mjs' export default async bud => { diff --git a/sources/@roots/bud-api/docs/entry/usage.md b/sources/@roots/bud-api/docs/entry/usage.md index d3b201cac3..5ea811deac 100644 --- a/sources/@roots/bud-api/docs/entry/usage.md +++ b/sources/@roots/bud-api/docs/entry/usage.md @@ -56,7 +56,7 @@ export default async bud => { ## Globbing -**bud.entry** can be used with [bud.glob](/docs/bud.glob) to find matching files. +**bud.entry** can be used with [bud.glob](/reference/bud.glob) to find matching files. ```js title='bud.config.mjs' export default async bud => { diff --git a/sources/@roots/bud-api/docs/watch/usage.md b/sources/@roots/bud-api/docs/watch/usage.md index af189814d1..e230315528 100644 --- a/sources/@roots/bud-api/docs/watch/usage.md +++ b/sources/@roots/bud-api/docs/watch/usage.md @@ -2,7 +2,7 @@ title: Usage --- -It is preferred to specify files using [bud.path](/docs/bud.path) or [bud.glob](/docs/bud.glob). +It is preferred to specify files using [bud.path](/reference/bud.path) or [bud.glob](/reference/bud.glob). ```typescript bud.watch(bud.path(`@src/pages/page.php`)) diff --git a/sources/@roots/bud-compiler/src/service.tsx b/sources/@roots/bud-compiler/src/service.tsx index e2f3181a99..0d945ebd24 100644 --- a/sources/@roots/bud-compiler/src/service.tsx +++ b/sources/@roots/bud-compiler/src/service.tsx @@ -20,7 +20,7 @@ import {pathToFileURL} from 'node:url' import {Error} from '@roots/bud-dashboard/components/error' import {Service} from '@roots/bud-framework/service' import {bind} from '@roots/bud-support/decorators/bind' -import {BudError, type BudHandler} from '@roots/bud-support/errors' +import {BudError, type BudErrorClass} from '@roots/bud-support/errors' import {duration} from '@roots/bud-support/human-readable' import {render} from '@roots/bud-support/ink' import stripAnsi from '@roots/bud-support/strip-ansi' @@ -100,7 +100,7 @@ export class Compiler extends Service implements BudCompiler { * {@link BudCompiler.onError} */ @bind - public onError(error: BudHandler | webpack.WebpackError) { + public onError(error: BudErrorClass | webpack.WebpackError) { process.exitCode = 1 this.app.server?.appliedMiddleware?.hot?.publish({error}) diff --git a/sources/@roots/bud-dashboard/package.json b/sources/@roots/bud-dashboard/package.json index 783cfd4783..7ab2c821c8 100644 --- a/sources/@roots/bud-dashboard/package.json +++ b/sources/@roots/bud-dashboard/package.json @@ -46,7 +46,7 @@ "type": "module", "exports": { ".": "./lib/index.js", - "./app": "./lib/app/index.js", + "./application": "./lib/application.js", "./components/*": "./lib/components/*.js", "./console": "./lib/console/index.js", "./helpers/*": "./lib/helpers/*.js", @@ -59,8 +59,8 @@ ".": [ "./lib/index.d.ts" ], - "app": [ - "./lib/app/index.d.ts" + "application": [ + "./lib/application.d.ts" ], "components/*": [ "./lib/components/*.d.ts" diff --git a/sources/@roots/bud-dashboard/src/application.tsx b/sources/@roots/bud-dashboard/src/application.tsx index a52c4aa36b..9bd297dc7d 100644 --- a/sources/@roots/bud-dashboard/src/application.tsx +++ b/sources/@roots/bud-dashboard/src/application.tsx @@ -1,6 +1,6 @@ import type {Bud} from '@roots/bud-framework' import type {StatsCompilation} from '@roots/bud-framework/config' -import type {BudHandler} from '@roots/bud-support/errors' +import type {BudErrorClass} from '@roots/bud-support/errors' import {exit} from 'node:process' @@ -27,7 +27,7 @@ export interface Props { displayAssets?: boolean displayEntrypoints?: boolean displayServerInfo?: boolean - error?: BudHandler + error?: BudErrorClass errors?: StatsCompilation[`errors`] isolated?: number mode: Bud['mode'] @@ -59,11 +59,13 @@ export const Application = ({ }: Props) => { if (error) return - if (!compilations?.length) return null + if (!compilations || !Array.isArray(compilations)) return null return ( {compilations?.map((compilation, id) => { + if (!compilation?.hash) return null + if (isolated > 0 && id + 1 !== isolated) return null return ( @@ -96,6 +98,7 @@ export const Application = ({ ) } +/* c8 ignore next 71 */ export const TeletypeApplication = ({ children, close, diff --git a/sources/@roots/bud-dashboard/src/components/error.tsx b/sources/@roots/bud-dashboard/src/components/error.tsx index 48ba19c3ff..5987d1e7aa 100644 --- a/sources/@roots/bud-dashboard/src/components/error.tsx +++ b/sources/@roots/bud-dashboard/src/components/error.tsx @@ -1,12 +1,12 @@ /* eslint-disable n/no-process-env */ import cleanStack from '@roots/bud-support/clean-stack' -import {BudError, type BudHandler} from '@roots/bud-support/errors' +import {BudError, type BudErrorClass} from '@roots/bud-support/errors' import figures from '@roots/bud-support/figures' import {Box, Text} from '@roots/bud-support/ink' import isString from '@roots/bud-support/lodash/isString' export type Props = React.PropsWithChildren<{ - error: BudHandler + error: BudErrorClass message?: string name?: string }> diff --git a/sources/@roots/bud-dashboard/src/service.tsx b/sources/@roots/bud-dashboard/src/service.tsx index b417fc69e4..a898524877 100644 --- a/sources/@roots/bud-dashboard/src/service.tsx +++ b/sources/@roots/bud-dashboard/src/service.tsx @@ -4,7 +4,7 @@ import type { StatsError, } from '@roots/bud-framework/config' import type {Dashboard as BudDashboard} from '@roots/bud-framework/services' -import type {BudHandler} from '@roots/bud-support/errors' +import type {BudErrorClass} from '@roots/bud-support/errors' import {stderr, stdin, stdout} from 'node:process' @@ -103,7 +103,7 @@ export class Dashboard extends Service implements BudDashboard { * {@link BudDashboard.render} */ @bind - public render(error?: BudHandler) { + public render(error?: BudErrorClass) { /** * Do not render if: * - dashboard is disabled diff --git a/sources/@roots/bud-dashboard/src/views/compilation.tsx b/sources/@roots/bud-dashboard/src/views/compilation.tsx index 2db4a75748..af6b9cfb05 100644 --- a/sources/@roots/bud-dashboard/src/views/compilation.tsx +++ b/sources/@roots/bud-dashboard/src/views/compilation.tsx @@ -42,6 +42,7 @@ const Compilation = ({ total, }: Props) => { const compilationColor = useCompilationColor(compilation) + return ( { {compilation.name?.split(`/`).pop() ?? `compilation`} - {` `} {total > 1 && ( - [{id}/{total}]{` `} + {` `}[{id}/{total}] )} {compilation.hash && ( - [{compilation.hash}]{` `} + {` `}[{compilation.hash}] )} {basedir && compilation.outputPath && ( - ./{relative(basedir, compilation.outputPath)} + ./{relative(`${basedir}`, `${compilation.outputPath}`)} )} @@ -119,18 +119,22 @@ const Footer = ({compilation}: Partial) => { if (!compilation || !compilation?.assets) return ... + const formattedErrorCount = + compilation.errorsCount > 1 + ? `${compilation.errorsCount} errors` + : `${compilation.errorsCount} error` + const cachedModuleCount = compilation.modules?.filter(mod => mod?.cached)?.length ?? 0 - const totalModuleCount = compilation.modules?.filter(mod => mod && mod.hasOwnProperty(`cached`)) ?.length ?? 0 - const formattedErrorCount = - compilation.errorsCount > 1 - ? `${compilation.errorsCount} errors` - : `${compilation.errorsCount} error` - const formattedModuleCount = `${cachedModuleCount}/${totalModuleCount} modules cached` + const formattedModuleCount = + cachedModuleCount > 0 + ? `${cachedModuleCount}/${totalModuleCount} modules cached` + : `${totalModuleCount} modules` + const formattedTime = `${duration(compilation.time)}` if (compilation.errorsCount > 0) { @@ -141,13 +145,20 @@ const Footer = ({compilation}: Partial) => { ) } - if (compilation.warningsCount > 0) { + if (totalModuleCount === 0) { + return ( + + {formattedTime} + + ) + } + + if (cachedModuleCount === 0) { return ( {formattedTime} - {` `} - [{formattedModuleCount}] + {` ${totalModuleCount} modules`} ) @@ -157,8 +168,7 @@ const Footer = ({compilation}: Partial) => { {formattedTime} - {` `} - [{formattedModuleCount}] + {{` [${formattedModuleCount}]`}} ) diff --git a/sources/@roots/bud-dashboard/src/views/entrypoints.tsx b/sources/@roots/bud-dashboard/src/views/entrypoints.tsx index 739c3d07de..178c29ecba 100644 --- a/sources/@roots/bud-dashboard/src/views/entrypoints.tsx +++ b/sources/@roots/bud-dashboard/src/views/entrypoints.tsx @@ -21,8 +21,8 @@ const Entrypoints = ({ if (!displayEntrypoints) return null if (!compilation?.entrypoints) return null - const entrypoints = Object.values(compilation.entrypoints).map( - entrypoint => ({ + const entrypoints = Object.values(compilation.entrypoints) + .map(entrypoint => ({ ...entrypoint, assets: entrypoint.assets?.map(asset => ({ @@ -30,8 +30,8 @@ const Entrypoints = ({ ...(compilation?.assets?.find(a => a?.name === asset?.name) ?? {}), })) ?? [], - }), - ) + })) + .filter(({assets}) => assets.length > 0) const minWidth = entrypoints.reduce( (longest, entry) => @@ -42,6 +42,8 @@ const Entrypoints = ({ 0, ) + if (entrypoints.length === 0) return null + return entrypoints.map(({assets, name}, key) => ( {compact ? ( diff --git a/sources/@roots/bud-dashboard/src/views/node-error.tsx b/sources/@roots/bud-dashboard/src/views/node-error.tsx index adafe10254..c4bf17df3e 100644 --- a/sources/@roots/bud-dashboard/src/views/node-error.tsx +++ b/sources/@roots/bud-dashboard/src/views/node-error.tsx @@ -1,18 +1,18 @@ -/* eslint-disable n/no-process-env */ +import {cwd, env} from 'node:process' + import cleanStack from '@roots/bud-support/clean-stack' -import {BudError, type BudHandler} from '@roots/bud-support/errors' +import {BudError, type BudErrorClass} from '@roots/bud-support/errors' import figures from '@roots/bud-support/figures' import {Box, Text} from '@roots/bud-support/ink' import isString from '@roots/bud-support/lodash/isString' export type Props = React.PropsWithChildren<{ - error: BudHandler + error: BudErrorClass message?: string name?: string }> -const basePath = - process.env.PROJECT_CWD ?? process.env.INIT_CWD ?? process.cwd() +const basePath = env.PROJECT_CWD ?? env.INIT_CWD ?? cwd() export const Error = ({error, ...props}: Props) => { if (!error) { diff --git a/sources/@roots/bud-dashboard/test/__snapshots__/app.test.tsx.snap b/sources/@roots/bud-dashboard/test/__snapshots__/app.test.tsx.snap deleted file mode 100644 index 135cdeaca6..0000000000 --- a/sources/@roots/bud-dashboard/test/__snapshots__/app.test.tsx.snap +++ /dev/null @@ -1,71 +0,0 @@ -// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html - -exports[`@roots/bud-dashboard app component > should not render entrypoints when entrypoint assets are undefined 1`] = ` -" -╭ compilation -│ -│ entrypoint -│ -╰ ... -" -`; - -exports[`@roots/bud-dashboard app component > should not render entrypoints when entrypoint assets are undefined 2`] = ` -" -╭ compilation -│ -│ entrypoint -│ -╰ ... -" -`; - -exports[`@roots/bud-dashboard app component > should not render entrypoints when entrypoints are undefined 1`] = ` -" -╭ compilation -│ -│ -╰ ... -" -`; - -exports[`@roots/bud-dashboard app component > should render assets 1`] = ` -" -╭ mock -│ -│ assets -│ › foo.png 1 kB -│ … 1 additional asset not shown -│ -╰ 0ms [0/0 modules cached] -" -`; - -exports[`@roots/bud-dashboard app component > should render compilation count for multi-compiler 1`] = ` -" -╭ mock [1/2] -│ -│ foo -│ › foo.js 1 kB -│ -╰ 0ms [0/0 modules cached] - -╭ mock [2/2] -│ -│ foo -│ › foo.js 1 kB -│ -╰ 0ms [0/0 modules cached] -" -`; - -exports[`@roots/bud-dashboard app component > should render entrypoints 1`] = ` -" -╭ mock -│ -│ foo -│ › foo.js 1 kB -│ -╰ 0ms [0/0 modules cached] -" -`; diff --git a/sources/@roots/bud-dashboard/test/app.test.tsx b/sources/@roots/bud-dashboard/test/app.test.tsx index 24f9dfdc60..9df71dac4f 100644 --- a/sources/@roots/bud-dashboard/test/app.test.tsx +++ b/sources/@roots/bud-dashboard/test/app.test.tsx @@ -1,14 +1,34 @@ -import React from '@roots/bud-support/ink' +import React, {Box} from '@roots/bud-support/ink' // @ts-ignore import {render} from 'ink-testing-library' import {describe, expect, it} from 'vitest' import stripAnsi from '@roots/bud-support/strip-ansi' -import {Application} from '../src/application' +import {Application} from '@roots/bud-dashboard/application' import {StatsCompilation} from 'webpack' +const enum Char { + TopLeft = `╭`, + TopRight = `╮`, + BottomLeft = `╰`, + BottomRight = `╯`, + Vertical = `│`, + Horizontal = `─`, + Empty = ``, + Space = ` `, + NewLine = `\n`, +} + +const startsWith = (line: string, char: Char) => + new RegExp(`^${char}`).test(line) + +const isFormattedAsset = (line: string) => + startsWith(line, Char.Vertical) && /›\s*/.test(line) + const mockCompilations: Array> = [ { name: `mock`, + hash: `mock-hash`, + outputPath: `/path/mock/to`, assets: [ { type: `asset`, @@ -43,130 +63,360 @@ const mockCompilations: Array> = [ }, ] -describe.skipIf(process.env.CI)( - `@roots/bud-dashboard app component`, - () => { - it(`should render entrypoints`, () => { - const {lastFrame} = render( - , - ) - - expect(stripAnsi(lastFrame())).toMatchSnapshot() - }) - - it(`should not render entrypoints when entrypoints is empty`, () => { - const {lastFrame} = render( - , - ) - }) - - it(`should not render entrypoints when entrypoints are undefined`, () => { - const {lastFrame} = render( - , - ) - - expect(stripAnsi(lastFrame())).toMatchSnapshot() - }) - - it(`should not render entrypoints when entrypoint assets are undefined`, () => { - const ink = render( - > = [ + { + ...mockCompilations[0], + errors: [new Error(`Bad error`)], + }, +] + +describe(`@roots/bud-dashboard app component`, () => { + it(`should not render without a hash`, () => { + const {lastFrame} = render( + // @ts-ignore + , + ) + expect(stripAnsi(lastFrame())).toBe(Char.NewLine) + }) + + it(`should render basedir when basedir prop and compilation.outputPath are set`, () => { + const {lastFrame} = render( + , + ) + const lines = stripAnsi(lastFrame()).split(Char.NewLine) + + expect(lines[0]).toBe(Char.Empty) + + expect(startsWith(lines[1], Char.TopLeft)).toBe(true) + expect(lines[1]).toMatch(/mock\s\[mock\-hash\]\s+\.\/\.\.\/to$/) + }) + + it(`should render entrypoints`, () => { + const {lastFrame} = render( + , + ) + const lines = stripAnsi(lastFrame()).split(Char.NewLine) + + expect(lines[0]).toBe(Char.Empty) + + expect(startsWith(lines[1], Char.TopLeft)).toBe(true) + expect(lines[1]).toMatch(/mock \[mock\-hash\]$/) + + expect(lines[2]).toBe(Char.Vertical) + + expect(startsWith(lines[3], Char.Vertical)).toBe(true) + expect(lines[3]).toMatch(/ foo/) + + expect(isFormattedAsset(lines[4])).toBe(true) + expect(lines[4]).toMatch(/\sfoo\.js\s/) + + expect(lines[5]).toBe(Char.Vertical) + + expect(startsWith(lines[6], Char.BottomLeft)).toBe(true) + expect(lines[6]).toMatch(/0ms$/) + + expect(lines[7]).toBe(Char.Empty) + expect(lines[8]).toBeUndefined() + }) + + it(`should not render entrypoints when entrypoints is empty`, () => { + const {lastFrame} = render( + , + ) + const lines = stripAnsi(lastFrame()).split(Char.NewLine) + expect(lines[0]).toBe(Char.Empty) + + expect(startsWith(lines[1], Char.TopLeft)).toBe(true) + expect(lines[1]).toMatch(/mock \[mock\-hash\]$/) + + expect(lines[2]).toBe(Char.Vertical) + expect(lines[3]).toBe(Char.Vertical) + + expect(startsWith(lines[4], Char.BottomLeft)).toBe(true) + expect(lines[4]).toMatch(/0ms$/) + + expect(lines[5]).toBe(Char.Empty) + }) + + it(`should not render entrypoints when entrypoints are undefined`, () => { + const {lastFrame} = render( + , + ) + + const lines = stripAnsi(lastFrame()).split(Char.NewLine) + expect(lines[0]).toBe(Char.Empty) + + expect(startsWith(lines[1], Char.TopLeft)).toBe(true) + expect(lines[1]).toMatch(/ compilation \[foo\]$/) + expect(lines[2]).toBe(Char.Vertical) + expect(lines[3]).toBe(Char.Vertical) + + expect(startsWith(lines[4], Char.BottomLeft)).toBe(true) + expect(lines[4]).toMatch(/...$/) + }) + + it(`should not render entrypoints when entrypoint assets are undefined`, () => { + const ink = render( + , - ) - - expect(stripAnsi(ink.lastFrame())).toMatchSnapshot() - - ink.rerender( - , + ) + let lines = stripAnsi(ink.lastFrame()).split(Char.NewLine) + expect(lines[0]).toBe(Char.Empty) + + expect(startsWith(lines[1], Char.TopLeft)).toBe(true) + expect(lines[1]).toMatch(/ compilation \[foo\]$/) + + expect(lines[2]).toBe(Char.Vertical) + expect(lines[3]).toBe(Char.Vertical) + + expect(startsWith(lines[4], Char.BottomLeft)).toBe(true) + expect(lines[4]).toMatch(/\.\.\.$/) + expect(lines[5]).toBe(Char.Empty) + + ink.rerender( + , - ) - - expect(stripAnsi(ink.lastFrame())).toMatchSnapshot() - }) - - it(`should render compilation count for multi-compiler`, () => { - const {lastFrame} = render( - , - ) - - expect(stripAnsi(lastFrame())).toMatchSnapshot() - }) - - it(`should render assets`, () => { - const {lastFrame} = render( - , - ) - - expect(stripAnsi(lastFrame())).toMatchSnapshot() - }) - - it(`should render server info`, () => { - const {lastFrame} = render( - , - ) - - expect(stripAnsi(lastFrame())).toMatch(/Network/) - expect(stripAnsi(lastFrame())).toMatch(/localhost:8080/) - expect(stripAnsi(lastFrame())).toMatch(/dev/) - expect(stripAnsi(lastFrame())).toMatch(/proxy/) - }) - }, -) + }, + ]} + displayEntrypoints={true} + />, + ) + + lines = stripAnsi(ink.lastFrame()).split(Char.NewLine) + expect(lines[0]).toBe(Char.Empty) + + expect(startsWith(lines[1], Char.TopLeft)).toBe(true) + expect(lines[1]).toMatch(/compilation \[foo\]$/) + expect(lines[2]).toBe(Char.Vertical) + expect(lines[3]).toBe(Char.Vertical) + + expect(startsWith(lines[4], Char.BottomLeft)).toBe(true) + expect(lines[4]).toMatch(/.../) + + expect(lines[5]).toBe(Char.Empty) + }) + + it(`should render compilation count for multi-compiler`, () => { + const {lastFrame} = render( + , + ) + + const lines = stripAnsi(lastFrame()).split(Char.NewLine) + expect(lines[0]).toBe(Char.Empty) + + expect(startsWith(lines[1], Char.TopLeft)).toBe(true) + expect(lines[1]).toMatch(/mock \[1\/2\] \[mock\-hash\]$/) + + expect(lines[2]).toBe(Char.Vertical) + expect(lines[3]).toMatch(/│ foo/) + expect(lines[4]).toMatch(/│ › foo.js /) + expect(lines[5]).toBe(Char.Vertical) + + expect(startsWith(lines[6], Char.BottomLeft)).toBe(true) + expect(lines[6]).toMatch(/0ms$/) + expect(lines[7]).toBe(Char.Empty) + + expect(startsWith(lines[8], Char.TopLeft)).toBe(true) + expect(lines[8]).toMatch(/mock \[2\/2\] \[mock\-hash\]$/) + + expect(lines[9]).toBe(Char.Vertical) + expect(lines[10]).toMatch(/│ foo/) + expect(lines[11]).toMatch(/│ › foo.js /) + expect(lines[12]).toBe(Char.Vertical) + expect(lines[13]).toMatch(/╰ 0ms/) + expect(lines[14]).toBe(Char.Empty) + }) + + it(`should render assets`, () => { + const {lastFrame} = render( + , + ) + const lines = stripAnsi(lastFrame()).split(Char.NewLine) + expect(lines[0]).toBe(Char.Empty) + + expect(startsWith(lines[1], Char.TopLeft)).toBe(true) + expect(lines[1]).toMatch(/mock \[mock\-hash\]$/) + + expect(lines[2]).toBe(Char.Vertical) + + expect(startsWith(lines[3], Char.Vertical)).toBe(true) + expect(lines[3]).toMatch(/│ assets/) + + expect(isFormattedAsset(lines[4])).toBe(true) + expect(lines[4]).toMatch(/foo.png/) + + expect(lines[5]).toMatch(/│ … 1 additional asset not shown/) + expect(lines[6]).toBe(Char.Vertical) + + expect(startsWith(lines[7], Char.BottomLeft)).toBe(true) + expect(lines[7]).toMatch(/0ms$/) + expect(lines[8]).toBe(Char.Empty) + }) + + it(`should render error`, () => { + const {lastFrame} = render( + , + ) + const lines = stripAnsi(lastFrame()).split(Char.NewLine) + expect(lines[0]).toBe(Char.Empty) + + expect(startsWith(lines[1], Char.TopLeft)).toBe(true) + expect(lines[1]).toMatch(/mock \[mock\-hash\]$/) + + expect(lines[2]).toBe(Char.Vertical) + expect(lines[3]).toMatch(/│ │ Bad error/) + expect(lines[4]).toBe(Char.Vertical) + + expect(startsWith(lines[5], Char.BottomLeft)).toBe(true) + expect(lines[5]).toMatch(/0ms$/) + expect(lines[6]).toBe(Char.Empty) + }) + + it(`should render server info`, () => { + const {lastFrame} = render( + , + ) + const lines = stripAnsi(lastFrame()).split(Char.NewLine) + expect(lines[0]).toBe(Char.Empty) + + expect(startsWith(lines[1], Char.TopLeft)).toBe(true) + expect(lines[1]).toMatch(/mock \[mock\-hash\]$/) + + expect(lines[2]).toBe(Char.Vertical) + expect(lines[3]).toMatch(/│ foo/) + + expect(isFormattedAsset(lines[4])).toBe(true) + expect(lines[4]).toMatch(/foo.js /) + expect(lines[4]).toMatch(/1 kB$/) + + expect(lines[5]).toBe(Char.Vertical) + + expect(startsWith(lines[6], Char.Vertical)).toBe(true) + expect(lines[6]).toMatch(/assets$/) + + expect(isFormattedAsset(lines[7])).toBe(true) + expect(lines[7]).toMatch(/ foo.png /) + expect(lines[7]).toMatch(/1 kB$/) + + expect(lines[8]).toMatch(/│ … 1 additional asset not shown/) + expect(lines[9]).toBe(Char.Vertical) + + expect(startsWith(lines[10], Char.BottomLeft)).toBe(true) + expect(lines[10]).toMatch(/0ms$$/) + + expect(lines[11]).toBe(Char.Empty) + expect(lines[12]).toMatch(/Network/) + expect(lines[13]).toMatch(/ › proxy ┄ http:\/\/localhost:\d+\//) + expect(lines[14]).toBe(Char.Empty) + expect(lines[15]).toMatch(/ ┄ http:\/\/example\.test\//) + expect(lines[16]).toMatch(/ › dev ┄ http:\/\/localhost:\d+\//) + expect(lines[17]).toMatch( + / ┄ http:\/\/\d+\.\d+\.\d+\.\d+:\d+\//, + ) + expect(lines[18]).toMatch(/ ┄ http:\/\/example\.test:\d+\//) + expect(lines[19]).toBe(Char.Empty) + }) + + it(`should not render proxy info when proxy not set`, () => { + const {lastFrame} = render( + , + ) + const lines = stripAnsi(lastFrame()).split(Char.NewLine) + expect(lines[13]).toMatch(/ › dev ┄ http:\/\/localhost:\d+\//) + }) + + it(`should not throw when crazy input happens`, () => { + const {lastFrame: basedirNumber} = render( + // @ts-ignore + , + ) + expect(basedirNumber()).toBe(Char.Empty) + + const {lastFrame: compilationTypeStringArray} = render( + // @ts-ignore + , + ) + expect(stripAnsi(compilationTypeStringArray())).toBe(Char.NewLine) + + const {lastFrame: compilationTypeNumberArray} = render( + // @ts-ignore + , + ) + expect(stripAnsi(compilationTypeNumberArray())).toBe(Char.NewLine) + + const {lastFrame: compilationTypeString} = render( + // @ts-ignore + , + ) + expect(stripAnsi(compilationTypeString())).toBe(Char.Empty) + }) +}) diff --git a/sources/@roots/bud-dashboard/test/service.test.tsx b/sources/@roots/bud-dashboard/test/service.test.tsx index f8030cdcca..86c8ca7b10 100644 --- a/sources/@roots/bud-dashboard/test/service.test.tsx +++ b/sources/@roots/bud-dashboard/test/service.test.tsx @@ -2,7 +2,7 @@ import {Bud, factory} from '@repo/test-kit' import {Service} from '@roots/bud-framework/service' import {beforeEach, describe, expect, it} from 'vitest' -import Dashboard from '../src/index.js' +import {Dashboard} from '@roots/bud-dashboard/service' describe(`@roots/bud-dashboard`, () => { let bud: Bud diff --git a/sources/@roots/bud-sass/src/extension.ts b/sources/@roots/bud-sass/src/extension.ts index 6cd9af37cb..f271f046c8 100644 --- a/sources/@roots/bud-sass/src/extension.ts +++ b/sources/@roots/bud-sass/src/extension.ts @@ -25,15 +25,13 @@ export class BudSass extends BudSassOptions { @bind public override async boot({build, postcss}) { postcss?.setSyntax(`postcss-scss`) - build.rules.sass.setUse(() => - [ - build.items[`precss`], - build.items[`css`], - build.items[`postcss`], - build.items[`resolve-url`], - build.items[`sass`], - ].filter(Boolean), - ) + build.rules.sass.setUse(() => [ + `precss`, + `css`, + `postcss`, + `resolve-url`, + `sass`, + ]) } /** @@ -67,7 +65,7 @@ export class BudSass extends BudSassOptions { ) } else { this.logger.warning( - `sass implementation not explicitly resolvable. falling back on sass loader default implementation.`, + `sass implementation not explicitly resolvable. falling back on default implementation.`, ) } diff --git a/sources/@roots/bud-support/src/errors/asError.ts b/sources/@roots/bud-support/src/errors/asError.ts deleted file mode 100644 index c3b2577a21..0000000000 --- a/sources/@roots/bud-support/src/errors/asError.ts +++ /dev/null @@ -1,25 +0,0 @@ -import {BudError} from './errors.js' - -interface ErrorWithMessage extends Error { - message: string - name: string -} - -export function isErrorWithMessage( - error: unknown, -): error is ErrorWithMessage { - return ( - typeof error === `object` && - error !== null && - `message` in error && - typeof (error as Record).message === `string` - ) -} - -export function asError(maybeError: unknown): ErrorWithMessage { - if (isErrorWithMessage(maybeError)) { - return maybeError - } - - return BudError.normalize(maybeError) -} diff --git a/sources/@roots/bud-support/src/errors/errors.ts b/sources/@roots/bud-support/src/errors/errors.ts deleted file mode 100644 index 9bfaa1b7db..0000000000 --- a/sources/@roots/bud-support/src/errors/errors.ts +++ /dev/null @@ -1,93 +0,0 @@ -/* eslint-disable n/no-process-env */ -import type {InstanceOptions} from 'modern-errors' - -import ModernError from 'modern-errors' - -interface BudErrorProps { - details: string - docs: URL - file: { - module: any - name: string - path: string - sha1: string - } - instance: string - isBudError: true - issues: URL - message: string - origin: BudHandler - thrownBy: string -} - -const BudBaseError = ModernError.subclass(`BaseError`, {}) - -class BudHandler extends BudBaseError { - public declare details: false | string - public declare docs: false | URL - public declare file: { - module: any - name: string - path: string - sha1: string - } - - public declare instance: `default` | string - public isBudError = true - public declare issues: false | URL - public declare origin: BudHandler | false - public declare thrownBy: false | string - - public constructor( - message: string, - options?: InstanceOptions & {props?: Partial}, - ) { - super(message, options) - - this.thrownBy = options?.props?.thrownBy ?? false - this.instance = options?.props?.instance ?? `default` - this.origin = options?.props?.origin ?? false - this.details = options?.props?.details ?? false - this.issues = options?.props?.issues ?? false - this.docs = options?.props?.docs ?? false - - this.isBudError = true - } -} - -const BudError = BudBaseError.subclass(`BudError`, { - custom: BudHandler, -}) - -const ModuleError = BudBaseError.subclass(`ModuleError`, { - custom: BudHandler, -}) - -const ConfigError = BudBaseError.subclass(`ConfigurationError`, { - custom: BudHandler, -}) - -const InputError = BudBaseError.subclass(`InputError`, { - custom: BudHandler, -}) -const CompilerError = BudBaseError.subclass(`CompilerError`, { - custom: BudHandler, -}) - -const ServerError = BudBaseError.subclass(`ServerError`, { - custom: BudHandler, -}) -const ExtensionError = BudBaseError.subclass(`ExtensionError`, { - custom: BudHandler, -}) - -export { - BudError, - BudHandler, - CompilerError, - ConfigError, - ExtensionError, - InputError, - ModuleError, - ServerError, -} diff --git a/sources/@roots/bud-support/src/errors/index.ts b/sources/@roots/bud-support/src/errors/index.ts index ea22105df8..1c03355085 100644 --- a/sources/@roots/bud-support/src/errors/index.ts +++ b/sources/@roots/bud-support/src/errors/index.ts @@ -1,2 +1,151 @@ -export * from './asError.js' -export * from './errors.js' +import type {InstanceOptions} from 'modern-errors' + +import ModernError from 'modern-errors' + +/** + * Props for Bud errors + */ +interface BudErrorProps { + details: string + docs: URL + file: { + module: any + name: string + path: string + sha1: string + } + instance: string + isBudError: true + issues: URL + message: string + origin: BudErrorClass + thrownBy: string +} + +/** + * Error base class + */ +class BudErrorClass extends ModernError { + /** + * Details + */ + public declare details: false | string + /** + * Documentation URL + */ + public declare docs: false | URL + + /** + * Information about file related to error + */ + public declare file: { + module: any + name: string + path: string + sha1: string + } + + /** + * Instance name containing error + */ + public declare instance: `default` | string + + /** + * Used to identify Bud errors + */ + public isBudError = true + + /** + * Issue tracker URL + */ + public declare issues: false | URL + + /** + * Original error + */ + public declare origin: BudErrorClass | false + + /** + * Name of method that threw error + */ + public declare thrownBy: false | string + + /** + * Class constructor + */ + public constructor( + message: string, + options?: InstanceOptions & {props?: Partial}, + ) { + super(message, options) + + this.thrownBy = options?.props?.thrownBy ?? false + this.instance = options?.props?.instance ?? `default` + this.origin = options?.props?.origin ?? false + this.details = options?.props?.details ?? false + this.issues = options?.props?.issues ?? false + this.docs = options?.props?.docs ?? false + + this.isBudError = true + } +} + +/** + * BudError + */ +const BudError = BudErrorClass.subclass(`BudError`, { + custom: BudErrorClass, +}) + +/** + * ModuleError + */ +const ModuleError = BudErrorClass.subclass(`ModuleError`, { + custom: BudErrorClass, +}) + +/** + * ConfigError + */ +const ConfigError = BudErrorClass.subclass(`ConfigurationError`, { + custom: BudErrorClass, +}) + +/** + * InputError + */ +const InputError = BudErrorClass.subclass(`InputError`, { + custom: BudErrorClass, +}) + +/** + * CompilerError + */ +const CompilerError = BudErrorClass.subclass(`CompilerError`, { + custom: BudErrorClass, +}) + +/** + * ServerError + */ +const ServerError = BudErrorClass.subclass(`ServerError`, { + custom: BudErrorClass, +}) + +/** + * ExtensionError + */ +const ExtensionError = BudErrorClass.subclass(`ExtensionError`, { + custom: BudErrorClass, +}) + +export { + BudError, + BudErrorClass, + CompilerError, + ConfigError, + ExtensionError, + InputError, + ModuleError, + ServerError, +} diff --git a/sources/@roots/bud/src/cli/commands/bud.build.tsx b/sources/@roots/bud/src/cli/commands/bud.build.tsx index 36d8e0fc95..7e0170cfe8 100644 --- a/sources/@roots/bud/src/cli/commands/bud.build.tsx +++ b/sources/@roots/bud/src/cli/commands/bud.build.tsx @@ -20,6 +20,7 @@ import html from '@roots/bud/cli/flags/html' import immutable from '@roots/bud/cli/flags/immutable' import input from '@roots/bud/cli/flags/input' import minimize from '@roots/bud/cli/flags/minimize' +import notify from '@roots/bud/cli/flags/notify' import output from '@roots/bud/cli/flags/output' import publicPath from '@roots/bud/cli/flags/publicPath' import runtime from '@roots/bud/cli/flags/runtime' @@ -94,6 +95,8 @@ export default class BudBuildCommand extends BudCommand { public minimize = minimize + public override notify = notify + public output = output public publicPath = publicPath @@ -120,6 +123,6 @@ export default class BudBuildCommand extends BudCommand { this.bud.entrypoints.set(`emitHtml`, this[`entrypoints.html`]) } - await this.bud?.run() + await this.bud.run() } } diff --git a/sources/@roots/bud/src/cli/commands/bud.tsx b/sources/@roots/bud/src/cli/commands/bud.tsx index b8f83e2eaf..97d004a0e4 100644 --- a/sources/@roots/bud/src/cli/commands/bud.tsx +++ b/sources/@roots/bud/src/cli/commands/bud.tsx @@ -7,7 +7,7 @@ import {env, exit} from 'node:process' import {Bud} from '@roots/bud-framework' import {Command, Option} from '@roots/bud-support/clipanion' import {bind} from '@roots/bud-support/decorators/bind' -import {BudError, BudHandler} from '@roots/bud-support/errors' +import {BudError, BudErrorClass} from '@roots/bud-support/errors' import {Box, render, Static} from '@roots/bud-support/ink' import logger from '@roots/bud-support/logger' import basedir from '@roots/bud/cli/flags/basedir' @@ -74,7 +74,7 @@ export default class BudCommand extends Command { public mode = mode - public notify = notify + public declare notify: typeof notify public silent = silent(true) @@ -252,7 +252,7 @@ export default class BudCommand extends Command { * Handle errors */ @bind - public override async catch(error: BudHandler): Promise { + public override async catch(error: BudErrorClass): Promise { if (!error.isBudError) error = BudError.normalize(error) if (this.bud?.notifier?.notify) {