Files

When writing a CodeEngine plugin, you'll be working with file objects. Every plugin receives file objects as input and returns file objects as output. But what are these file objects?

Virtual Files

The first thing to be aware of is that a "file" in CodeEngine doesn't necessarily correspond to a file on your hard drive. A file in CodeEngine is just an object that represents a chunk of data. That data could have come from a file on the hard drive, or on the network, or from an FTP site, or from a database, or a CMS, or an RSS feed, or any other source.

That said, most files in CodeEngine typically come from the filesystem, so it's easy to think of them that way. And CodeEngine files have properties like path, dir, name, and extension that make them feel like filesystem files.

File objects

CodeEngine plugins receive File objects, which they can then manipulate in any way they want. These objects have the following properties:

Property Name	Type	Description
path	string	The path and file name, relative to the destination
dir	string	The directory path, relative to the destination
name	string	The file name, including the file extension
extension	string	The file extension
contents	Buffer	The raw file contents as bytes. This is useful for dealing with binary files, such as images.
text	string	The file contents as a UTF-8 string. This is useful for dealing with all sorts of text files, such as HTML, CSS, etc.
size	number	The size of the file, in bytes
createdAt	Date	The date/time that the file was first created
modifiedAt	Date	The date/time that the file was last modified
metadata	object	Arbitrary data added by plugins. All properties of this object must be cloneable.
source	string	A URL that indicates the original source of this file. This may be a file:// URL, a web URL, or even a custom URL scheme that's specific to a particular plugin.
sourceMap	sourcemap object or undefined	A source map that maps the file's current contents back to its original source contents. Not all plugins create source maps, so this object may be null.

File paths

File objects have several path properties, such as path, dir, name, and extension. Setting any of these properties also updates the other properties accordingly, so they're always in-sync with each other.

Here are some examples of each of the path properties:

path	dir	name	extension
index.html	(empty string)	index.html	.html
css/styles.min.css	css	styles.min.css	.css
img/logos/vector.svg	img/logos	vector.svg	.svg
blog/articles/2019/05/17/post	blog/articles/2019/05/17	post	(empty string)
.gitignore	(empty string)	.gitignore	(empty string)

FileInfo objects

Most CodeEngine plugins just modify the File object that they receive as input and return that same object as their output. However, some plugins need to create new files. To do that, they can simply return a plain-old JavaScript object (POJO) with the following properties:

NOTE: Only the path property is required. All other properties are optional.

Property Name	Type	Description
path	string	The file path, relative to the destination. For example, "index.html" or "img/logos/vector.svg".
createdAt	Date	The date/time that the file was originally created
modifiedAt	Date	The date/time that the file was last modified
contents	string or Buffer or Uint8Array or ArrayBuffer	The raw file contents as bytes
text	string	The file contents as a UTF-8 string
metadata	object	Arbitrary data. All properties of this object must be cloneable.
source	string or URL	A URL that indicates the original source of this file, if applicable. This can be a file:// URL, a web URL, or even a custom URL scheme that's specific to your plugin.
sourceMap	sourcemap object	A source map that maps the file's current contents back to its original source contents