dir4json

A toolset for output directories/files structure to JSON

What is this?

Even if you want to search for directories and files that serve as assets or resources at runtime, you cannot do so in environments like browsers. You're probably looking for a list of those directories and files.

dir4json is a Vite plugin and CLI toolset for TypeScript/JavaScript environments that makes this easy to achieve.

Using dir4json, this directory structure is generated as JSON during the build process:

public
├── images
│   ├── foo.jpg
│   └── bar.png
└── baz.mp3

{
  "public/": {   // Directory
    "images/": {   // Sub directory
      "foo.jpg": {   // File
        "size": 15344   // File size
      },
      "bar.png": {
        "size": 43791
      }
    },
    "baz.mp3": {
      "size": 115563
    }
  }
}

Features

• Automatically emits a JSON file containing the files under the specified directories. You can import the "Metadata JSON," serve it from your web server, and reuse it in many ways.
• As a Vite plugin, it generates metadata JSON during build time simply by being integrated. It can also be used as a CLI interface.
• Files inside subdirectories are collected as well, and the directory hierarchy is preserved as nested JSON objects.
• Each file entry records its size by default, and you can opt in to timestamps, MIME types, or hashes.
• Optionally calculate hashes (md5, sha1, or anything supported by Node's crypto) and embed them in the metadata.

Environment

• NPM enviroment (TypeScript/JavaScript)
• Vite 5.0 or higher.

Installation

Install it as a devDependency:

npm install -D dir4json

Or, to use it globally as a CLI:

npm install -g dir4json

Configure as a Vite Plugin

Enable the plugins in vite.config.ts:

// Import dir4json
import dir4json from 'dir4json';

export default defineConfig({
  plugins: [
    // Use dir4json plugin
    dir4json({
      dirs: [
        'public/images/',  // Directories to capture
        'src/asset/',
      ]
    }),
  ],
  // ...
});

Specify the directory paths you want to export through the dirs option. When the build runs, the metadata JSON is written to src/generated/dirMetadata.json.

If you include additional attributes such as mime and mtime, the generated JSON looks like this:

{
  "public": {   // Directory
    "images": {   // Sub directory
      "foo.jpg": {   // File
        "size": 15344,   // File size in bytes
        "mime": "image/jpeg",   // MIME type
        "mtime": "2018-1-23T12:34:56Z"  // ISO timestamp
      },
      "bar.png": {
        "size": 43791,
        "mime": "image/png",
        "mtime": "2020-4-12T21:13:27Z"
      }
    },
    "baz.mp3": {
      "size": 115563,
      "mime": "audio/mpeg",
      "mtime": "2022-5-13T11:42:54Z"
    }
  },
  "src": {
    "asset": {
      "data": {
        "data.db": {
          // ...
        }
      }
    }
  }
}

This allows you to easily access the directory structure:

// Import the JSON to use instantly:
import dirMetadata from './generated/dirMetadata.json';

// Look up a specific file
const barImage = dirMetadata['public/']['images/']['bar.png'];
console.log(`bar size: ${barImage.size} bytes`);

// Walk through a directory node
Object.entries(dirMetadata['src/']['asset/']).forEach(([name, entry]) => {
  console.log(`${name}: ${entry.mime}`);
});

You could publish JSON on a web server and load it using fetch API.

Configure as a Command Line Interface

dir4json also ships with a small CLI so you can regenerate metadata without Vite. The CLI treats the current working directory as the project root.

npx dir4json --output src/generated/images.json public/images/

• The positional dir argument is optional; when omitted, entries are loaded from .dir4jsonrc.
• --output, --attributes, --hashFormat, and --baseDir mirror the DirectoryEntry fields.
• Attribute lists accept comma-separated values such as --attributes size,mtime,sha256.

Other features

Other features, see repository document.

Discussions and Pull Requests

For discussions, please refer to the GitHub Discussions page. We have currently stopped issue-based discussions.

Pull requests are welcome! Please submit them as diffs against the develop branch and squashed changes before send.

License

Under MIT.