code-engine-source-filesystem

CodeEngine Filesystem Source

This is a CodeEngine plugin that reads files from the filesystem (local disk or network).

NOTE: This plugin is already built-into the CodeEngine CLI, so you may not need to use it directly unless you are using CodeEngine's programmatic API.

Installation

Install using npm.

npm install code-engine-source-filesystem

Usage

If you're using the CodeEngine CLI, then this plugin is already built-in, and you can use it simply by specifying a source path in your generator.

export default {
  source: "my/source/directory",
};

Or you can set source to a glob pattern to match specific files.

export default {
  source: "my/source/directory/**/*.{html,css,jpg,gif,png}",
};

If you need to set more advanced options, then you will need to explicitly import and use code-engine-source-filesystem.

import filesystem from "code-engine-source-filesystem";
 
export default {
  source: filesystem({
    path: "my/source/directory",
    filter: [
      "**/*.html",
      "css/*.css",
      "img/*.{jpg,gif,png}"
    ]
  }),
};

Options

You can set several options to customize the behavior of the code-engine-source-filesystem plugin. The only required option is path. All others are optional.

path

The relative or absolute filesystem path to read. Can be any of the following:

• A file path
• A directory path
• A glob pattern

NOTE: Setting path to a glob pattern is actually just a shorthand for setting path to the directory portion of the glob pattern and setting filter to the glob portion. This means you cannot set path to a glob and also set the filter option.

filter

One or more glob patterns, regular expressions, or filter functions that limit which files are read. By default, all files in all sub-directories are read.

The filter option can be set to a glob pattern, like this:

import filesystem from "code-engine-source-filesystem";
 
export default {
  source: filesystem({
    path: "my/source/directory",
    filter: "**/*.html"
  }),
};

It can also be set to a regular expression. For example, here's a filter that matches all .htm and .html files:

import filesystem from "code-engine-source-filesystem";
 
export default {
  source: filesystem({
    path: "my/source/directory",
    filter: /\.html?$/
  }),
};

You can also use a custom function that accepts a CodeEngine File object and returns true if the file should be read. Here's a filter that only matches files that do not have the word "draft" in their name:

import filesystem from "code-engine-source-filesystem";
 
export default {
  source: filesystem({
    path: "my/source/directory",
    filter: (file) => !file.name.includes("draft")
  }),
};

You can even specify multiple filters using an array. The plugin will read files that match any of the filter criteria. Here's a filter that will match HTML files, any file in the img directory, or any file that does not have the word "draft" in the name:

import filesystem from "code-engine-source-filesystem";
 
export default {
  source: filesystem({
    path: "my/source/directory",
    filter: [
      /\.html?$/,
      "img/**/*",
      (file) => !file.name.includes("draft")
    ]
  }),
};

Another option is to specify separate include and exclude criteria. Each of these can be a single filter or an array of filters. For example, here's a filter that will apply to HTML files or files in in the img directory, but only if they don't contain the word "draft" in the name:

import filesystem from "code-engine-source-filesystem";
 
export default {
  source: filesystem({
    path: "my/source/directory",
    filter: {
      include: [
        /\.html?$/,
        "img/**/*",
      },
      exclude: (file) => file.name.includes("draft")
    }
  }),
};

deep

Determines the depth of sub-directories that will be read. Can be any of the following:

• A number that indicates the depth of sub-directories to crawl
• Infinity or true to crawl all sub-directories
• Zero or false to only read the top-level directory contents

Defaults to true.

fs

This option allows you to provide your own custom implementation of the Node.js filesystem module. Examples of packages you could substitute include:

• graceful-fs
• virtual-fs
• fs-in-memory

Contributing

Contributions, enhancements, and bug-fixes are welcome! Open an issue on GitHub and submit a pull request.

Building

To build the project locally on your computer:

1. Clone this repo
   git clone https://github.com/CodeEngineOrg/code-engine-source-filesystem.git

2. Install dependencies
   npm install

3. Build the code
   npm run build

4. Run the tests
   npm test

License

code-engine-source-filesystem is 100% free and open-source, under the MIT license. Use it however you want.

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Big Thanks To

Thanks to these awesome companies for their support of Open Source developers ❤