✨ feat(minor): add acorn opt-out (#2503)

- add some opt-out methods to roots/sage extension - update documentation ## Type of change **PATCH: backwards compatible change**
roots · Nov 28, 2023 · c3b224f · c3b224f
1 parent ffc9e17
commit c3b224f
Show file tree

Hide file tree

Showing 220 changed files with 2,970 additions and 1,884 deletions.
diff --git a/examples/babel/bud.config.js b/examples/babel/bud.config.js
@@ -1,6 +1,7 @@
+/**
+ * @param {import('@roots/bud').Bud} bud
+ */
 export default async bud => {
-  bud.entry('app', ['app.js', 'app.css'])
-
   bud.babel
     .setPresets({
       '@babel/preset-env': '@babel/preset-env',
@@ -11,4 +12,7 @@ export default async bud => {
         {helpers: false},
       ],
     })
+    .done()
+
+    .entry('app', ['app.js'])
 }
diff --git a/examples/babel/jsconfig.json b/examples/babel/jsconfig.json
@@ -0,0 +1,5 @@
+{
+  "compilerOptions": {
+    "types": ["@roots/bud", "@roots/bud-babel"]
+  }
+}
diff --git a/examples/config-json/bud.config.json b/examples/config-json/bud.config.json
@@ -1,9 +1,13 @@
 {
-  "entry": ["app", ["app.js"]],
-  "babel": {
-    "setPluginOptions": [
+  entry: ["app", ["app.js"]],
+
+  /**
+   * Comments are okay
+   */
+  babel: {
+    setPluginOptions: [
       "@babel/plugin-transform-runtime",
-      {"helpers": false, "regenerator": false}
+      {helpers: false, regenerator: false}
     ]
   }
 }
diff --git a/examples/config-yml/bud.config.yml b/examples/config-yml/bud.config.yml
@@ -36,9 +36,9 @@ hash: >
 webpackConfig: >
   => config => ({...config, parallelism: 1})
 
-# or dynamic values
+# logs: `[@examples/config-yml] › 2 + 2 equals 4`
 log:
-  - => 2 + 2
+  - 2 + 2
   - => `equals ${2 + 2}`
 
 # For anything that can't be accomplished
@@ -56,7 +56,7 @@ tapAsync: >
     bud.log('hi!', '...eventually')
   }
 
-# Bringin' it all together
+# logs: `[@examples/config-yml] › cache enabled`
 when:
   - _bud.cache.enabled
   - => bud => bud.log('cache enabled')

diff --git a/examples/multi-compiler/bud.config.ts b/examples/multi-compiler/bud.config.ts
@@ -5,20 +5,24 @@ import {bud} from '@roots/bud'
  *
  * Each can be uniquely configured.
  */
-await Promise.all([
+await bud.sequence([
   /**
    * Make `theme` workspace in `./theme` and setup entrypoints
    * Files will be output to `./theme/dist`
    */
-  bud.make({label: 'theme', basedir: bud.path('theme')}, async theme =>
-    theme.entry('theme', ['theme.js', 'theme.css']),
-  ),
+  async bud =>
+    await bud.make(
+      {label: 'theme', basedir: bud.path('theme')},
+      async theme => theme.entry('theme', ['theme.js', 'theme.css']),
+    ),
 
   /**
    * Make plugin workspace in `./plugin` and setup entrypoints
    * Files will be output to `./plugin/dist`
    */
-  bud.make({label: 'plugin', basedir: bud.path('plugin')}, async plugin =>
-    plugin.entry('plugin', ['plugin.js', 'plugin.css']),
-  ),
+  async bud =>
+    await bud.make(
+      {label: 'plugin', basedir: bud.path('plugin'), dependsOn: [`theme`]},
+      async plugin => plugin.entry('plugin', ['plugin.js', 'plugin.css']),
+    ),
 ])
diff --git a/examples/multi-compiler/test.html b/examples/multi-compiler/test.html
@@ -0,0 +1,8 @@
+<html>
+<head>
+    <title>Multi Compiler Test</title>
+</head>
+<body>
+    <h1>Multi Compiler Test</h1>
+</body>
+</html>
diff --git a/examples/sage/bud.config.js b/examples/sage/bud.config.js
@@ -1,10 +1,10 @@
 // @ts-check
 
 /**
- * @param {import('@roots/bud').Bud} app
+ * @param {import('@roots/bud').Bud} bud
  */
-export default async (app) => {
-  app
+export default async bud => {
+  bud
     .entry({
       app: ['@scripts/app', '@styles/app'],
       editor: ['@scripts/editor', '@styles/editor'],
@@ -14,7 +14,7 @@ export default async (app) => {
     .serve(3000)
     .proxy('http://example.test')
 
-  app.wpjson
+  bud.wpjson
     .useTailwindColors(true)
     .useTailwindFontFamily()
     .useTailwindFontSize()

diff --git a/examples/swc/src/styles.css b/examples/swc/src/styles.css
@@ -1,3 +1,19 @@
+html,
 body {
-  background-color: white;
+  padding: 0;
+  margin: 0;
+}
+
+#root {
+  align-items: center;
+  background: rgb(88, 19, 213);
+  color: white;
+  display: flex;
+  font-family: sans-serif;
+  height: 100vh;
+  justify-content: center;
+  letter-spacing: 0.2em;
+  text-align: center;
+  text-transform: uppercase;
+  width: 100vw;
 }
diff --git a/examples/wordpress-theme/.eslintrc.js b/examples/wordpress-theme/.eslintrc.js
diff --git a/examples/wordpress-theme/bud.config.yml b/examples/wordpress-theme/bud.config.yml
@@ -1,8 +1,23 @@
-setPublicPath: /app/themes/your-theme-name/dist/
-
 entry:
   app: [app.js, app.css]
   editor: [editor.js]
 
+entrypoints.setEmitHtml: true
+
+eslint.extends:
+  - ['@roots/eslint-config']
+
+setPublicPath: /app/themes/your-theme-name/
+
+tailwind.extend:
+  colors:
+    blue:
+      100: '#ebf8ff'
+      200: '#bee3f8'
+      300: '#90cdf4'
+      400: '#63b3ed'
+      500: '#4299e1'
+
 wpjson:
   enable: true
+  useTailwindColors: true
diff --git a/examples/wordpress-theme/package.json b/examples/wordpress-theme/package.json
@@ -9,7 +9,9 @@
   "devDependencies": {
     "@roots/bud": "workspace:*",
     "@roots/bud-eslint": "workspace:*",
+    "@roots/bud-postcss": "workspace:*",
     "@roots/bud-preset-wordpress": "workspace:*",
-    "@roots/bud-swc": "workspace:*"
+    "@roots/bud-swc": "workspace:*",
+    "@roots/bud-tailwindcss": "workspace:*"
   }
 }
diff --git a/examples/wordpress-theme/src/app.js b/examples/wordpress-theme/src/app.js
@@ -1,3 +1,5 @@
+/* eslint-disable */
+
 import React from 'react'
 import {createRoot} from 'react-dom/client'
 import {App} from './components/App.js'

diff --git a/examples/wordpress-theme/src/components/App.js b/examples/wordpress-theme/src/components/App.js
@@ -1,5 +1,3 @@
-import React from 'react'
-
 export const App = () => (
   <div className="app">
     <input

diff --git a/examples/wordpress-theme/theme.json b/examples/wordpress-theme/theme.json
@@ -5,7 +5,34 @@
   "settings": {
     "color": {
       "custom": false,
-      "customGradient": false
+      "customGradient": false,
+      "palette": [
+        {
+          "color": "#ebf8ff",
+          "name": "Blue 100",
+          "slug": "blue-100"
+        },
+        {
+          "color": "#bee3f8",
+          "name": "Blue 200",
+          "slug": "blue-200"
+        },
+        {
+          "color": "#90cdf4",
+          "name": "Blue 300",
+          "slug": "blue-300"
+        },
+        {
+          "color": "#63b3ed",
+          "name": "Blue 400",
+          "slug": "blue-400"
+        },
+        {
+          "color": "#4299e1",
+          "name": "Blue 500",
+          "slug": "blue-500"
+        }
+      ]
     },
     "custom": {
       "spacing": {},
@@ -16,7 +43,14 @@
     },
     "spacing": {
       "padding": true,
-      "units": ["px", "%", "em", "rem", "vw", "vh"]
+      "units": [
+        "px",
+        "%",
+        "em",
+        "rem",
+        "vw",
+        "vh"
+      ]
     },
     "typography": {
       "customFontSize": false,

diff --git a/sources/@repo/docs/content/extensions/sage/index.mdx b/sources/@repo/docs/content/extensions/sage/index.mdx
@@ -28,3 +28,17 @@ The [Sage docs](https://docs.roots.io/sage/10.x/compiling-assets) cover everythi
 ## Included extensions
 
 <IncludedExtensions />
+
+## Acorn compatibility
+
+[roots/sage](https://github.com/roots/sage) is built with the [roots/acorn](https://github.com/roots/acorn) framework. This preset guarantees compatibility with Acorn's API for enqueuing JS and CSS.
+
+If you do not wish to use Acorn to enqueue assets you can disable the Acorn extension:
+
+```ts title=bud.config.ts
+export default async (bud: Bud) => {
+  bud.sage.acorn.enable(false)
+}
+```
+
+This will restore the default behavior of including the public path (e.g. `/app/themes/sage/public`) in entrypoints manifest values.
diff --git a/sources/@repo/docs/content/reference/bud.addConfig/index.mdx b/sources/@repo/docs/content/reference/bud.addConfig/index.mdx
@@ -0,0 +1,14 @@
+---
+title: bud.addConfig
+description: Parse and execute a configuration module
+---
+
+Parses and executes a configuration module.
+
+## Usage
+
+```js title=bud.config.js
+export default async bud => {
+  await bud.addConfig(`./config/index.js`)
+}
+```
diff --git a/sources/@repo/docs/content/reference/bud.after.mdx b/sources/@repo/docs/content/reference/bud.after.mdx
@@ -1,6 +1,9 @@
 ---
 title: bud.after
 description: Do something after compilation has completed
+tags:
+  - facade
+  - lifecycle
 ---
 
 **bud.after** can be used to do tasks after a compilation has completed.

diff --git a/sources/@repo/docs/content/reference/bud.alias.mdx b/sources/@repo/docs/content/reference/bud.alias.mdx
@@ -1,6 +1,9 @@
 ---
 title: bud.alias
 description: Register shorthand for resolving modules
+tags:
+  - configuration
+  - facade
 ---
 
 **bud.alias** is a helper function for creating aliases. Unlike paths, aliases may be used in your application scripts and stylesheets.

diff --git a/sources/@repo/docs/content/reference/bud.assets/index.mdx b/sources/@repo/docs/content/reference/bud.assets/index.mdx
@@ -4,8 +4,8 @@ description: Include static assets in your compilation even if they aren't refer
 custom_edit_url: 'https://github.com/roots/bud/tree/main/sources/@roots/bud-api/docs/assets'
 tags:
   - assets
+  - configuration
   - filesystem
-  - config
 ---
 
 import Overview from '@site/../../@roots/bud-api/docs/assets/overview.md'

diff --git a/sources/@repo/docs/content/reference/bud.bundle.mdx b/sources/@repo/docs/content/reference/bud.bundle.mdx
@@ -1,6 +1,9 @@
 ---
 title: bud.bundle
 description: Specify a set of assets to include in the compilation.
+tags:
+  - configuration
+  - facade
 ---
 
 Split specified modules into a separate chunk

diff --git a/sources/@repo/docs/content/reference/bud.config/index.mdx b/sources/@repo/docs/content/reference/bud.config/index.mdx
@@ -1,10 +1,9 @@
 ---
 title: bud.config
-description: Modify the generated webpack config directly
+description: Modify the generated webpack config directly prior to compilation
 custom_edit_url: 'https://github.com/roots/bud/tree/main/sources/@roots/bud-api/docs/config'
 tags:
-  - assets
-  - config
+  - configuration
 ---
 
 import Overview from '@site/../../@roots/bud-api/docs/config/overview.md'

diff --git a/sources/@repo/docs/content/reference/bud.copyDir/index.mdx b/sources/@repo/docs/content/reference/bud.copyDir/index.mdx
@@ -4,7 +4,7 @@ description: Copy a directory to the distribution directory
 custom_edit_url: 'https://github.com/roots/bud/tree/main/sources/@roots/bud-api/docs/copyDir'
 tags:
   - assets
-  - config
+  - configuration
 ---
 
 import Overview from '@site/../../@roots/bud-api/docs/copyDir/overview.md'

diff --git a/sources/@repo/docs/content/reference/bud.copyFile/index.mdx b/sources/@repo/docs/content/reference/bud.copyFile/index.mdx
@@ -4,7 +4,7 @@ description: Copy a file to the distribution directory
 custom_edit_url: 'https://github.com/roots/bud/tree/main/sources/@roots/bud-api/docs/copyFile'
 tags:
   - assets
-  - config
+  - configuration
 ---
 
 import Overview from '@site/../../@roots/bud-api/docs/copyFile/overview.md'

diff --git a/sources/@repo/docs/content/reference/bud.define/index.mdx b/sources/@repo/docs/content/reference/bud.define/index.mdx
@@ -1,9 +1,9 @@
 ---
 title: bud.define
-description: Replace variables in your application code and templates at compile time.
+description: Replace variables in your application code and templates at compile time
 custom_edit_url: 'https://github.com/roots/bud/tree/main/sources/@roots/bud-api/docs/define'
 tags:
-  - config
+  - configuration
 ---
 
 import Overview from '@site/../../@roots/bud-api/docs/define/overview.md'
-Original file line number
+Diff line change
@@ Expand Up / @@ -4,7 +4,7 @@ description: Copy a directory to the distribution directory @@
     custom_edit_url: 'https://github.com/roots/bud/tree/main/sources/@roots/bud-api/docs/copyDir'
     tags:
       - assets
-      - config
+      - configuration
     ---
     import Overview from '@site/../../@roots/bud-api/docs/copyDir/overview.md'
@@ Expand Down @@