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:
loading...
Options
A copy task can take the following options:
src
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
.
Type: string
dest
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.
Type: string
warn
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
.
Type: boolean
keepDirStructure
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
.
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' }
]
}
]
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 }
]
}
]