Assets

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:

@font-face {
  font-family: 'MyFont';
  src: url(@src/fonts/MyFont.woff2) format('woff2');
}

The 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):

TS

bud.config.ts

import type {Bud} from '@roots/bud'

export default async (bud: Bud) => {
  bud.assets(['images', 'fonts'])
}

JS

bud.config.js

/** @param {import('@roots/bud').Bud} bud */
export default async (bud) => {
  bud.assets(['images', 'fonts'])
}

YML

bud.config.yml

assets: [['images', 'fonts']]

JSON

bud.config.json

{
  "assets": [["images", "fonts"]]
}

If you want more control over the directory being output to, you can use an array of from/to pairs:

TS

bud.config.ts

import type {Bud} from '@roots/bud'

export default async (bud: Bud) => {
  bud.assets([
    ['images', 'assets/images'], // from `@src/images` to `@dist/assets/images`
    ['fonts', 'assets/fonts'], // from `@src/fonts` to `@dist/assets/fonts`
  ])
}

JS

bud.config.js

/** @param {import('@roots/bud').Bud} bud */
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`
  ])
}

YML

bud.config.yml

assets: [[['images', 'assets/images'], ['fonts', 'assets/fonts']]]

JSON

bud.config.json

{
  "assets": [[["images", "assets/images"], ["fonts", "assets/fonts"]]]
}

For complete control, you can pass an object:

TS

bud.config.ts

import type {Bud} from '@roots/bud'

export default async (bud: Bud) => {
  import type {Bud} from '@roots/bud'
  
  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`,
    })
  }
}

JS

bud.config.js

/** @param {import('@roots/bud').Bud} bud */
export default async (bud) => {
  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`,
    })
  }
}

YML

bud.config.yml

assets:
  from: bud => bud.path('@src', 'images')
  to: bud => bud.path('@dist', 'images', '@name')
  context: bud => bud.path('@src')
  noErrorOnMissing: true
  toType: template

JSON

bud.config.json

{
  "assets": {
    "from": "bud => bud.path('@src', 'images')",
    "to": "bud => bud.path('@dist', 'images', '@name')",
    "context": "bud => bud.path('@src')",
    "noErrorOnMissing": true,
    "toType": "template"
  }
}

You can learn more about this and other details in the bud.assets documentation.