{"id":45748889,"url":"https://github.com/filearchitect/filearchitect","last_synced_at":"2026-02-25T17:43:03.018Z","repository":{"id":270023491,"uuid":"909125827","full_name":"filearchitect/filearchitect","owner":"filearchitect","description":"Create file and folder structures from simple text outlines","archived":false,"fork":false,"pushed_at":"2026-01-13T20:45:07.000Z","size":565,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-13T22:29:39.666Z","etag":null,"topics":["file-structure","files","filesystem","folders","macos","management"],"latest_commit_sha":null,"homepage":"https://filearchitect.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/filearchitect.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-27T19:51:17.000Z","updated_at":"2026-01-13T20:45:10.000Z","dependencies_parsed_at":"2025-03-24T05:21:04.749Z","dependency_job_id":"f2891881-6e70-4d50-8047-ec8c40f322cf","html_url":"https://github.com/filearchitect/filearchitect","commit_stats":null,"previous_names":["seblavoie/file-architect-core","filearchitect/file-architect-core","filearchitect/filearchitect"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/filearchitect/filearchitect","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filearchitect%2Ffilearchitect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filearchitect%2Ffilearchitect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filearchitect%2Ffilearchitect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filearchitect%2Ffilearchitect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/filearchitect","download_url":"https://codeload.github.com/filearchitect/filearchitect/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filearchitect%2Ffilearchitect/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29832976,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-25T17:17:09.781Z","status":"ssl_error","status_checked_at":"2026-02-25T17:16:50.421Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["file-structure","files","filesystem","folders","macos","management"],"created_at":"2026-02-25T17:43:01.220Z","updated_at":"2026-02-25T17:43:03.010Z","avatar_url":"https://github.com/filearchitect.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# File Architect\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://filearchitect.com\" target=\"_blank\"\u003eWebsite\u003c/a\u003e |\n  \u003ca href=\"https://filearchitect.com/docs\" target=\"_blank\"\u003eDocumentation\u003c/a\u003e\n\u003c/p\u003e\n\nCreate 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.\n\nThis code powers the mac app available at [filearchitect.com](https://filearchitect.com)\n\n## Note\n\nThis is still a work-in-progress and might have some breaking changes\n\n## Features\n\n-   📁 Create directory structures using a simple, indentation-based syntax\n-   📋 Copy files and directories from existing locations\n-   🔄 Move (import) files from other projects\n-   🚀 Available as both a CLI tool and a TypeScript/JavaScript library\n-   🌐 Works in both Node.js and browser environments\n-   ⚡ Supports YAML frontmatter for configuration\n-   🔍 Preview structure operations before execution\n\n## Installation\n\n### CLI Tool\n\n```bash\nnpm install -g @filearchitect/cli\n# or\npnpm add -g @filearchitect/cli\n# or\nyarn global add @filearchitect/cli\n```\n\n### Library\n\n```bash\nnpm install @filearchitect/core\n# or\npnpm add @filearchitect/core\n# or\nyarn add @filearchitect/core\n```\n\n## Quick Start\n\n### Using the CLI\n\n1. Create a structure file (`structure.txt`):\n\n```txt\nsrc\n    components\n        Button.tsx\n        Card.tsx\n    styles\n        global.css\n```\n\n2. Create the structure:\n\n```bash\nfilearchitect create structure.txt my-project\n```\n\n### Using the Library\n\n```typescript\nimport { createStructure } from \"@filearchitect/core\";\n\nconst structure = `\nsrc\n    components\n        Button.tsx\n        Card.tsx\n    styles\n        global.css\n`;\n\n// Uses Node.js filesystem by default\nawait createStructure(structure, {\n    rootDir: \"./my-project\",\n});\n\n// Or with additional options\nawait createStructure(structure, {\n    rootDir: \"./my-project\",\n    replacements: {\n        files: [{ search: \".js\", replace: \".ts\" }],\n    },\n});\n```\n\n## Syntax Guide\n\n| Syntax                | Description                                        | Example                                 |\n| --------------------- | -------------------------------------------------- | --------------------------------------- |\n| `name.ext`            | Creates an empty file                              | `file.txt`                              |\n| `name`                | Creates a directory                                | `folder`                                |\n| `[source]`            | Copies a file or folder with its contents          | `[~/path/to/config.json]`               |\n| `[souce] \u003e name.ext`  | Copies and renames a file or folder                | `[~/path/to/config.json] \u003e config.json` |\n| `(source)`            | Moves (imports) a file or folder with its contents | `(~/path/to/file.txt)`                  |\n| `(source) \u003e name.ext` | Moves and renames a file or folder                 | `(~/old.txt) \u003e new.txt`                 |\n\n### YAML Frontmatter\n\nYou can include YAML frontmatter at the start of your structure file to configure replacements:\n\n```yaml\n---\nfileReplacements:\n    - search: \".js\"\n      replace: \".ts\"\nfolderReplacements:\n    - search: \"api\"\n      replace: \"rest\"\n---\nsrc\napi\nindex.js\n```\n\n### Complete Example\n\n```txt\n---\nfileReplacements:\n  - search: \".js\"\n    replace: \".ts\"\n---\nsrc\n    components\n        Button.tsx\n        Card.tsx\n        forms\n            LoginForm.tsx\n            SignupForm.tsx\n    styles\n        global.css\n        components.css\n    utils\n        [~/templates/api.js] \u003e api.ts\n        helpers.ts\n    types\n        index.d.ts\n\n# Copy configuration files\nconfig\n    [~/configs/base.json] \u003e base.json\n    [~/templates/react] \u003e template\n\n# Import existing files\ntests\n    (~/old-project/components/Button.test.tsx) \u003e components/Button.test.tsx\n    (~/old-project/utils/helpers.test.ts) \u003e utils/helpers.test.ts\n```\n\nThis creates:\n\n```\nmy-project/\n├── src/\n│   ├── components/\n│   │   ├── Button.tsx\n│   │   ├── Card.tsx\n│   │   └── forms/\n│   │       ├── LoginForm.tsx\n│   │       └── SignupForm.tsx\n│   ├── styles/\n│   │   ├── global.css\n│   │   └── components.css\n│   ├── utils/\n│   │   ├── api.ts        # Copied and renamed from ~/templates/api.js\n│   │   └── helpers.ts\n│   └── types/\n│       └── index.d.ts\n├── config/\n│   ├── base.json         # Copied from ~/configs/base.json\n│   └── template/         # Copied from ~/templates/react\n└── tests/\n    ├── components/\n    │   └── Button.test.tsx  # Moved from ~/old-project/components/Button.test.tsx\n    └── utils/\n        └── helpers.test.ts  # Moved from ~/old-project/utils/helpers.test.ts\n```\n\n## CLI Usage\n\n```bash\n# Create a structure\nfilearchitect create structure.txt output\n\n# Preview operations without creating\nfilearchitect show structure.txt output\n```\n\n## Library Usage\n\n```typescript\nimport { createStructure } from \"@filearchitect/core\";\n\nconst structure = `\nsrc\n    components\n        Button.tsx\n        Card.tsx\n    styles\n        global.css\n`;\n\n// Uses Node.js filesystem by default\nawait createStructure(structure, {\n    rootDir: \"./my-project\",\n});\n\n// Or with additional options\nawait createStructure(structure, {\n    rootDir: \"./my-project\",\n    replacements: {\n        files: [{ search: \".js\", replace: \".ts\" }],\n    },\n});\n```\n\n## API Reference\n\n### createStructure(input: string, options: CreateStructureOptions)\n\nCreates a file structure from a text description.\n\n#### Parameters\n\n-   `input`: The text description of the structure to create\n-   `options`: Configuration options\n    -   `rootDir`: The root directory where the structure will be created (required)\n    -   `fs`: Custom filesystem implementation (optional)\n    -   `replacements`: File and folder name replacements (optional)\n        -   `files`: Replacements for file names\n        -   `folders`: Replacements for folder names\n        -   `all`: Replacements applied to both files and folders\n\n#### Returns\n\nA promise that resolves to a `GetStructureResult` containing the operations performed.\n\n### getStructure(input: string, options: GetStructureOptions)\n\nParses a structure description and returns the operations that would be performed.\n\n#### Parameters\n\n-   `input`: The text description of the structure\n-   `options`: Configuration options\n    -   `rootDir`: The root directory where the structure would be created (required)\n    -   `fs`: Custom filesystem implementation (optional)\n    -   `replacements`: File and folder name replacements (optional)\n        -   `files`: Replacements for file names\n        -   `folders`: Replacements for folder names\n        -   `all`: Replacements applied to both files and folders\n\n#### Returns\n\nA promise that resolves to a `GetStructureResult` containing the operations that would be performed.\n\n## Browser Usage\n\nFile Architect also works in the browser with an in-memory filesystem:\n\n```typescript\nimport { createStructure, BrowserFileSystem } from \"@filearchitect/core\";\n\nconst fs = new BrowserFileSystem();\n\n// Browser requires explicit filesystem\nawait createStructure(structureText, \"/\", {\n    fs, // Browser filesystem must be provided explicitly\n    replacements: {\n        files: [{ search: \".js\", replace: \".ts\" }],\n    },\n});\n\n// Access the in-memory files\nconst files = fs.getFiles();\nconst directories = fs.getDirectories();\n```\n\n## Structure Operations\n\nWhen using `getStructure`, you get access to all planned operations before execution:\n\n```typescript\nimport { getStructure } from \"@filearchitect/core\";\n\nconst { operations } = await getStructure(structureText, {\n    rootDir: \"./output\",\n});\n```\n\nEach operation has the following structure:\n\n```typescript\ninterface StructureOperation {\n    // Type of operation: \"create\", \"copy\", \"move\", or \"included\"\n    type: \"create\" | \"copy\" | \"move\" | \"included\";\n\n    // Target path where the file/directory will be created\n    targetPath: string;\n\n    // For copy/move operations, the source path\n    sourcePath?: string;\n\n    // Whether this is a directory or file\n    isDirectory: boolean;\n\n    // Indentation depth in the original structure\n    depth: number;\n\n    // Base name of the file/directory\n    name: string;\n\n    // Warning message if there might be an issue\n    warning?: string;\n}\n```\n\nYou can use these operations to:\n\n-   Preview changes before execution\n-   Create custom validation rules\n-   Implement your own file processing logic\n-   Generate documentation about the structure\n\n## ZIP Archive Support\n\nFile Architect also provides a ZIP archiver to bundle your generated files:\n\n```typescript\nimport { createStructure, ZipArchiver } from \"@filearchitect/core\";\n\n// Create your file structure\nawait createStructure(structureText, \"./output\");\n\n// Create a ZIP archive of the results\nconst zipArchiver = new ZipArchiver({ relativeTo: \"./output\" });\n\n// Add specific files or directories\nawait zipArchiver.addFile(\"./output/config.json\", '{\"key\": \"value\"}');\nawait zipArchiver.addDirectory(\"./output/src\");\n\n// Add files from the filesystem\nawait zipArchiver.addFromFileSystem([\n    \"./output/package.json\",\n    \"./output/README.md\",\n]);\n\n// Generate the ZIP archive\nconst zipOutput = await zipArchiver.generate(\"buffer\"); // or \"blob\" for browser\n\n// In Node.js, you can write the buffer to disk\nimport fs from \"fs\";\nfs.writeFileSync(\"project.zip\", zipOutput.data);\n```\n\nThe ZIP archiver works in both Node.js and browser environments.\n\n## Practical Examples\n\n### Generate a React Component\n\n```txt\nsrc\n    components\n        Button\n            Button.tsx\n            Button.module.css\n            index.ts\n            Button.test.tsx\n```\n\n### Create a Project Scaffold\n\n```txt\n---\nfileReplacements:\n  - search: \"MyProject\"\n    replace: \"TaskManager\"\n---\nMyProject\n    src\n        index.ts\n        models\n            User.ts\n            Task.ts\n        services\n            api.ts\n        components\n            layout\n                Header.tsx\n                Footer.tsx\n            shared\n                Button.tsx\n                Card.tsx\n    public\n        index.html\n        assets\n            logo.svg\n    tests\n        unit\n            models\n                User.test.ts\n    README.md\n    package.json\n    tsconfig.json\n```\n\n### Import from an Existing Project\n\n```txt\n# Create a new project with files from multiple sources\nnew-project\n    # Copy configuration files\n    [~/templates/typescript/tsconfig.json]\n    [~/templates/eslint/.eslintrc.js]\n\n    # Import key components from another project\n    src\n        components\n            (~/old-project/src/components/Button.tsx)\n            (~/old-project/src/components/Card.tsx)\n\n        # Add new files\n        pages\n            Home.tsx\n            About.tsx\n            Contact.tsx\n```\n\n## Contributing\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/filearchitect/filearchitect.git\ncd filearchitect\n```\n\n2. Install dependencies:\n\n```bash\npnpm install\n```\n\n3. Build the packages:\n\n```bash\npnpm build\n```\n\n4. Try it out:\n\n```bash\npnpm cli create structure.txt output\n```\n\n## License\n\nMIT\n\n## Roadmap\n\nFile Architect is actively developed. Upcoming features include:\n\n-   **Remote Sources**: Import files from GitHub, npm packages, and other remote sources\n-   **Folder with dots in their names**: This is a known issue\n\nWant to contribute? Check the [issues](https://github.com/filearchitect/filearchitect/issues) for opportunities!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilearchitect%2Ffilearchitect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffilearchitect%2Ffilearchitect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilearchitect%2Ffilearchitect/lists"}