Directory Structure

Introduction

Although we provide an opinionated directory structure, your application can theoretically be arranged in any way you like as no paths are hardcoded.
The only exceptions to this are the location of your .env file and the structure of your commands directory, which must follow the Topics pattern defined by the OCLIF framework.

Application Structure

  • app/
    • commands/
    • config/
    • contracts/
    • hooks/
    • modules/
      • acts/
      • auditions/
      • exceptions/
    • providers/
    • schemas/
    • templates/
  • bin/
  • prisma/
  • storage/
  • test/
    • commands/

Root directory

The project root contains the following important files.
File
Purpose
Docs
.editorconfig
IDE helper file to unify with framework patterns.
.env
Your environment-specific key-value config.
.eslintrc / .eslintignore
Unifies your code style with the framework.
.gitignore
Informs git to avoid committing certain files.
.npmrc
Allows npm overrides, such as avoiding default Chromium download with Puppeteer.
.prettierrc / .prettierignore
Tool to help enforce clean code standards on the project.
package.json
Used to configure your package.
tsconfig.json
Defines TypeScript build settings.

App directory

Your application's root directory. All files in this directory will be compiled by TypeScript and exported to the lib directory.

Commands

When you run a command from the CLI, the OCLIF framework will look for matches in this directory. Think about commands like the entry-points to your app.

Config

Contains your configuration files which can be created fresh or extended from the Backstage framework core configurations.

Contracts

Your TypeScript typings. Any changes to the shape of your classes should be modified here.

Hooks

Any hooks you would like to define for the command lifecycle. Any new hooks must be added to your package.json file.
Available lifecycle stages defined by OCLIF are init, prerun,postrun, and command_not_found

Modules

Modules directory can contain any number of miscellaneous groupings, however, some common ones are predefined.

Acts

The collection of your automation logic, grouped into Acts and Scenes.

Auditions

Tests against known detection vendors to analyse the effectiveness of your bot and operational environment.

Exceptions

Define custom exceptions here to make throwing errors cleaner and strongly typed.

Providers

All Service Providers should be located in this directory and exported from the index. Most of the core Backstage providers are extended here by default to allow customisation, however any number of providers can be implemented depending on the needs of your application.

Schemas

Your Zod validation logic should be defined here. You can define validation scopes however you like, but we recommend one file per scope.

Templates

You can customise your make: command templates here. We looked at several templating packages, however nearly all are designed for generating HTML rather than JavaScript files, so we opted to use native ES6 templating syntax.

Prisma directory

Prisma is the recommended database driver for your application. The configuration files and any flat file sqlite databases should be defined here.
We recommend reading more about Prisma in their docs before getting started.

Storage Directory

The storage directory is a folder for transient data such as screenshots and profiles (i.e. userDataDir). It can be structured however you like, however if you are using the Profiles module we recommend against renaming the profiles subdirectory.

Test directory

This directory contains your applications Mocha tests. More information about writing and running tests is covered in the Testing section.