@factorialco/shadowdog

Shadowdog 🐾

Shadowdog is a Node.js package for generating artifacts as derivative processes of files in your project. Whether you need to generate static assets, precompiled resources, or any other transformations, Shadowdog makes it easy and powerful with its supercharged feature set.

Features 🚀

• Flexible Input Detection: Automatically detects changes in files and processes only the updated ones.
• Configurable Pipelines: Define artifact generation workflows using an intuitive JSON configuration file.
• Plugin Support: Extend functionality with custom or community-built plugins.
• Blazing Fast Performance: Optimized for speed, even with large repositories.
• Watch Mode: Automatically regenerate artifacts when source files change.

---

Installation

Install Shadowdog via npm:

npm install shadowdog --save-dev

---

Getting started 🐕

Shadowdog uses a configuration file (shadowdog.json) to define workflows for generating artifacts. Here’s an example:

{
  "$schema": "https://raw.githubusercontent.com/factorialco/shadowdog/refs/heads/main/src/config/schema.json",
  "plugins": [],
  "watchers": [
    {
      "files": ["example.txt"],
      "commands": [
        {
          "artifacts": [
            {
              "output": "example.output.txt"
            }
          ],
          "command": "cp example.txt example.output.txt"
        }
      ]
    }
  ]
}

Key fields

• $schema: Provides schema validation for the configuration.
• plugins: An array of plugin names to extend Shadowdog's functionality.
• watchers: Defines file watchers that trigger artifact generation commands.
  • files: An array of file paths or glob patterns to watch.
  • commands: Commands to execute when changes are detected.
    • artifacts: Specifies the output files generated by the command.
    • command: The shell command to run.

---

CLI commands

Shadowdog provides a variety of commands to simplify your workflows:

• Generate artifacts:

  npx shadowdog
  

• Watch mode:

  npx shadowdog --watch
  

---

Available plugins 🧩

Enhance Shadowdog with these powerful plugins:

• shadowdog-local-cache
  Implements a local caching mechanism to speed up repeated artifact generation.

• shadowdog-remote-aws-s3-cache
  Enables remote caching with AWS S3 for distributed workflows.

• shadowdog-tag
  Adds tagging capabilities to filter specific commands.

• shadowdog-git Handles git rebases and merges smoothly pausing the watcher and resuming it after the rebase is done.

• shadowdog-socket
  Provides an external communication channel for interacting with Shadowdog.

• shadowdog-tree
  Generate a dependency tree structure between commands to run different commands that depend on each other.

• shadowdog-rake
  Optimize multiple bundle exec rake commmands into a single command.

Using plugins

To use a plugin, add it to the plugins section of your shadowdog.json configuration file. For example:

Update your configuration:

{
  ...
  "plugins": [
    {
      "name": "shadowdog-local-cache",
    },
    {
     "name" : "shadowdog-tree"
    }
  ]
  ...
}

Take into account that the order of plugins is important. The plugins will be executed in the order they are defined in the configuration file.

---

License 📄

Shadowdog is open source and available under the MIT License.

---

Feedback & Support ❤️

If you encounter any issues, have questions, or want to suggest features, please open an issue or join the discussions.

---

Enjoy artifact generation, supercharged! 🐾