Website | Documentation

Create file and folder structures with plain text. Write the file and folder structures you want to create and nest them with tabs. Perfect for scaffolding projects, creating templates, and organizing files.

This code powers the mac app available at filearchitect.com

This is still a work-in-progress and might have some breaking changes

• 📁 Create directory structures using a simple, indentation-based syntax
• 📋 Copy files and directories from existing locations
• 🔄 Move (import) files from other projects
• 🚀 Available as both a CLI tool and a TypeScript/JavaScript library
• 🌐 Works in both Node.js and browser environments
• ⚡ Supports YAML frontmatter for configuration
• 🔍 Preview structure operations before execution

npm install -g @filearchitect/cli
# or
pnpm add -g @filearchitect/cli
# or
yarn global add @filearchitect/cli

npm install @filearchitect/core
# or
pnpm add @filearchitect/core
# or
yarn add @filearchitect/core

1. Create a structure file (structure.txt):

src
    components
        Button.tsx
        Card.tsx
    styles
        global.css

2. Create the structure:

filearchitect create structure.txt my-project

import { createStructure } from "@filearchitect/core";

const structure = `
src
    components
        Button.tsx
        Card.tsx
    styles
        global.css
`;

// Uses Node.js filesystem by default
await createStructure(structure, {
    rootDir: "./my-project",
});

// Or with additional options
await createStructure(structure, {
    rootDir: "./my-project",
    replacements: {
        files: [{ search: ".js", replace: ".ts" }],
    },
});

You can include YAML frontmatter at the start of your structure file to configure replacements:

---
fileReplacements:
    - search: ".js"
      replace: ".ts"
folderReplacements:
    - search: "api"
      replace: "rest"
---
src
api
index.js

---
fileReplacements:
  - search: ".js"
    replace: ".ts"
---
src
    components
        Button.tsx
        Card.tsx
        forms
            LoginForm.tsx
            SignupForm.tsx
    styles
        global.css
        components.css
    utils
        [~/templates/api.js] > api.ts
        helpers.ts
    types
        index.d.ts

# Copy configuration files
config
    [~/configs/base.json] > base.json
    [~/templates/react] > template

# Import existing files
tests
    (~/old-project/components/Button.test.tsx) > components/Button.test.tsx
    (~/old-project/utils/helpers.test.ts) > utils/helpers.test.ts

This creates:

my-project/
├── src/
│   ├── components/
│   │   ├── Button.tsx
│   │   ├── Card.tsx
│   │   └── forms/
│   │       ├── LoginForm.tsx
│   │       └── SignupForm.tsx
│   ├── styles/
│   │   ├── global.css
│   │   └── components.css
│   ├── utils/
│   │   ├── api.ts        # Copied and renamed from ~/templates/api.js
│   │   └── helpers.ts
│   └── types/
│       └── index.d.ts
├── config/
│   ├── base.json         # Copied from ~/configs/base.json
│   └── template/         # Copied from ~/templates/react
└── tests/
    ├── components/
    │   └── Button.test.tsx  # Moved from ~/old-project/components/Button.test.tsx
    └── utils/
        └── helpers.test.ts  # Moved from ~/old-project/utils/helpers.test.ts

# Create a structure
filearchitect create structure.txt output

# Preview operations without creating
filearchitect show structure.txt output

import { createStructure } from "@filearchitect/core";

const structure = `
src
    components
        Button.tsx
        Card.tsx
    styles
        global.css
`;

// Uses Node.js filesystem by default
await createStructure(structure, {
    rootDir: "./my-project",
});

// Or with additional options
await createStructure(structure, {
    rootDir: "./my-project",
    replacements: {
        files: [{ search: ".js", replace: ".ts" }],
    },
});

Creates a file structure from a text description.

• input: The text description of the structure to create
• options: Configuration options
  • rootDir: The root directory where the structure will be created (required)
  • fs: Custom filesystem implementation (optional)
  • replacements: File and folder name replacements (optional)
    • files: Replacements for file names
    • folders: Replacements for folder names
    • all: Replacements applied to both files and folders

A promise that resolves to a GetStructureResult containing the operations performed.

Parses a structure description and returns the operations that would be performed.

• input: The text description of the structure
• options: Configuration options
  • rootDir: The root directory where the structure would be created (required)
  • fs: Custom filesystem implementation (optional)
  • replacements: File and folder name replacements (optional)
    • files: Replacements for file names
    • folders: Replacements for folder names
    • all: Replacements applied to both files and folders

A promise that resolves to a GetStructureResult containing the operations that would be performed.

File Architect also works in the browser with an in-memory filesystem:

import { createStructure, BrowserFileSystem } from "@filearchitect/core";

const fs = new BrowserFileSystem();

// Browser requires explicit filesystem
await createStructure(structureText, "/", {
    fs, // Browser filesystem must be provided explicitly
    replacements: {
        files: [{ search: ".js", replace: ".ts" }],
    },
});

// Access the in-memory files
const files = fs.getFiles();
const directories = fs.getDirectories();

When using getStructure, you get access to all planned operations before execution:

import { getStructure } from "@filearchitect/core";

const { operations } = await getStructure(structureText, {
    rootDir: "./output",
});

Each operation has the following structure:

interface StructureOperation {
    // Type of operation: "create", "copy", "move", or "included"
    type: "create" | "copy" | "move" | "included";

    // Target path where the file/directory will be created
    targetPath: string;

    // For copy/move operations, the source path
    sourcePath?: string;

    // Whether this is a directory or file
    isDirectory: boolean;

    // Indentation depth in the original structure
    depth: number;

    // Base name of the file/directory
    name: string;

    // Warning message if there might be an issue
    warning?: string;
}

You can use these operations to:

• Preview changes before execution
• Create custom validation rules
• Implement your own file processing logic
• Generate documentation about the structure

File Architect also provides a ZIP archiver to bundle your generated files:

import { createStructure, ZipArchiver } from "@filearchitect/core";

// Create your file structure
await createStructure(structureText, "./output");

// Create a ZIP archive of the results
const zipArchiver = new ZipArchiver({ relativeTo: "./output" });

// Add specific files or directories
await zipArchiver.addFile("./output/config.json", '{"key": "value"}');
await zipArchiver.addDirectory("./output/src");

// Add files from the filesystem
await zipArchiver.addFromFileSystem([
    "./output/package.json",
    "./output/README.md",
]);

// Generate the ZIP archive
const zipOutput = await zipArchiver.generate("buffer"); // or "blob" for browser

// In Node.js, you can write the buffer to disk
import fs from "fs";
fs.writeFileSync("project.zip", zipOutput.data);

The ZIP archiver works in both Node.js and browser environments.

src
    components
        Button
            Button.tsx
            Button.module.css
            index.ts
            Button.test.tsx

---
fileReplacements:
  - search: "MyProject"
    replace: "TaskManager"
---
MyProject
    src
        index.ts
        models
            User.ts
            Task.ts
        services
            api.ts
        components
            layout
                Header.tsx
                Footer.tsx
            shared
                Button.tsx
                Card.tsx
    public
        index.html
        assets
            logo.svg
    tests
        unit
            models
                User.test.ts
    README.md
    package.json
    tsconfig.json

# Create a new project with files from multiple sources
new-project
    # Copy configuration files
    [~/templates/typescript/tsconfig.json]
    [~/templates/eslint/.eslintrc.js]

    # Import key components from another project
    src
        components
            (~/old-project/src/components/Button.tsx)
            (~/old-project/src/components/Card.tsx)

        # Add new files
        pages
            Home.tsx
            About.tsx
            Contact.tsx

1. Clone the repository:

git clone https://github.com/filearchitect/filearchitect.git
cd filearchitect

2. Install dependencies:

pnpm install

3. Build the packages:

pnpm build

4. Try it out:

pnpm cli create structure.txt output

MIT

File Architect is actively developed. Upcoming features include:

• Remote Sources: Import files from GitHub, npm packages, and other remote sources
• Folder with dots in their names: This is a known issue

Want to contribute? Check the issues for opportunities!