Skip to main content
Version: v4.15

Copy Tasks for Output Targets

All of Stencil's non-documentation output targets (dist-custom-elements, dist, and www) support a copy config which allows you to define file copy operations which Stencil will automatically perform as part of the build. This could be useful if, for instance, you had some static assets like images which should be distributed alongside your components.

The copy attribute on these output targets expects an array of objects corresponding to the following CopyTask interface:

CopyTask
/**
 * A file and/or directory copy operation that may be specified as part of
 * certain output targets for Stencil (in particular `dist`,
 * `dist-custom-elements`, and `www`).
 */
export interface CopyTask {
  /**
   * The source file path for a copy operation. This may be an absolute or
   * relative path to a directory or a file, and may also include a glob
   * pattern.
   *
   * If the path is a relative path it will be treated as relative to
   * `Config.srcDir`.
   */
  src: string;
  /**
   * An optional destination file path for a copy operation. This may be an
   * absolute or relative path.
   *
   * If relative, this will be treated as relative to the output directory for
   * the output target for which this copy operation is configured.
   */
  dest?: string;
  /**
   * Whether or not Stencil should issue warnings if it cannot find the
   * specified source files or directories. Defaults to `false`.
   *
   * To receive warnings if a copy task source can't be found set this to
   * `true`.
   */
  warn?: boolean;
  /**
   * Whether or not directory structure should be preserved when copying files
   * from a source directory. Defaults to `true` if no `dest` path is supplied,
   * else it defaults to `false`.
   *
   * If this is set to `false`, all the files from a source directory will be
   * copied directly to the destination directory, but if it's set to `true` they
   * will be copied to a new directory inside the destination directory with
   * the same name as their original source directory.
   *
   * So if, for instance, `src` is set to `"images"` and `keepDirStructure` is
   * set to `true` the copy task will then produce the following directory
   * structure:
   *
   * ```
   * images
   * └── foo.png
   * dist
   * └── images
   *     └── foo.png
   * ```
   *
   * Conversely if `keepDirStructure` is set to `false` then files in `images/`
   * will be copied to `dist` without first creating a new subdirectory,
   * resulting in the following directory structure:
   *
   * ```
   * images
   * └── foo.png
   * dist
   * └── foo.png
   * ```
   *
   * If a `dest` path is supplied then `keepDirStructure`
   * will default to `false`, so that Stencil will write the
   * copied files directly into the `dest` directory without creating a new
   * subdirectory. This behavior can be overridden by setting
   * `keepDirStructure` to `true`.
   */
  keepDirStructure?: boolean;
}

Examples​

Images in the www Output Target​

The copy config within the following www output target config will cause Stencil to copy the entire directory from src/images to www/images:

  outputTargets: [
    {
      type: 'www',
      copy: [
        { src: 'images' }
      ]
    }
  ]

In this example, since the srcDir property is not set, the default source directory is src/, and since dest is not set the contents of src/images will be copied to a new images directory in www, the default destination directory for the www Output Target.

Setting the dest option​

The dest property can also be optionally set on a CopyTask to either an absolute path or a path relative to the build directory of the output target.

In this example we've customized the build directory to be public instead of the default ('www'), which, in combination with dest: 'static/web-fonts' will copy the contents of src/files/fonts over to public/static/web-fonts:

  outputTargets: [
    {
      type: 'www',
      dir: 'public',
      copy: [
        { src: 'files/fonts', dest: 'static/web-fonts' }
      ]
    }
  ]
note

When dest is set on a CopyTask Stencil will, by default, copy all the contents of the src directory to the dest directory without creating a new subdirectory for the contents of src. The keepDirStructure option can control this behavior. If it's set to true Stencil will always create a new subdirectory within dest with the same name as the src directory. In the above example this would result in the contents of src/files/fonts being copied to public/static/web-fonts/fonts instead of public/static/web-fonts.

See the above documentation for the keepDirStructure option for more details.

Opting-in to warnings​

By default, Stencil will not log a warning if a file or directory specified in src cannot be located. To opt-in to warnings if a copy task source cannot be found, set warn: true in the CopyTask object, like so:

  outputTargets: [
    {
      type: 'dist',
      copy: [
        { src: 'fonts', warn: true }
      ]
    }
  ]

Contents

Edit this page