mkstruct

mkstruct

Generate folder and file structures from plain text lists or ASCII trees in seconds.

mkstruct@2.0 ships a faster tree normalizer, smarter file detection, and a slimmer CLI tailored for everyday scaffolding workflows.

Why mkstruct v2

• Auto-format detection – Paste a flat list or an ASCII tree; mkstruct figures it out.
• Tree normalization – Cleans up mixed characters, tabs, and uneven spacing before parsing.
• Robust file detection – Recognises extensionless files such as Makefile, Dockerfile, and dotfiles.
• Safety first – Prevents writes outside the current working directory and supports dry-run previews.
• CLI ergonomics – Zero config with npx, inline structures via -s, piping with --stdin, and verbose tracing when you need insight.

Requires Node.js 14.0.0 or newer.

Installation

Use case	Command
Try once with npx	npx mkstruct structure.txt
Install globally	npm install -g mkstruct
Add to a project	npm install --save-dev mkstruct

Each option exposes the same mkstruct binary.

Quick Start

Flat list input

Create structure.txt:

src/index.js
src/utils/api.js
src/components/Button.jsx
public/index.html
README.md

Generate:

npx mkstruct structure.txt

ASCII tree input

Create tree.txt:

├── src
│   ├── index.js
│   ├── utils
│   │   └── api.js
│   └── components
│       └── Button.jsx
├── public
│   └── index.html
└── README.md

Generate:

npx mkstruct tree.txt

mkstruct automatically detects the format and creates folders before files so hierarchies stay intact.

CLI Reference

mkstruct [file] [options]

Flag	Description
-d, --dry-run	Preview actions without touching the file system
-f, --force	Overwrite files that already exist
-s, --structure <text>	Supply the structure inline (great for snippets)
--stdin	Read structure from standard input (pipe support)
-v, --verbose	Show parsing and normalization diagnostics
-h, --help	Display usage information

Common patterns

Preview output:

mkstruct structure.txt --dry-run

Pipe a remote definition:

curl -s https://example.com/structure.txt | mkstruct --stdin

Inline structure on the fly:

mkstruct -s "api/\n├── routes/\n│   └── users.js\n└── server.js"

Regenerate boilerplate forcefully:

mkstruct structure.txt --force

Inspect normalization behaviour:

mkstruct tree.txt --verbose

Input Guidelines

Flat format rules

• Use forward slashes (/) to separate folders.
• Provide one path per line; blank lines are ignored.
• Lines with extensions are treated as files; others become folders unless they match common filenames.

ASCII tree rules

• Use the standard characters ├──, └──, and │ (single- or double-dash variants both work).
• Indent with four spaces or tabs—mkstruct normalizes mixed indentation.
• Root nodes without connectors are supported (project as the first line, for example).

Example:

project
├── src
│   ├── index.js
│   └── utils
│       └── helper.js
└── README.md

Recipes

React starter

src/App.jsx
src/main.jsx
src/components/Navbar.jsx
src/components/Hero.jsx
src/components/Footer.jsx
src/pages/Home.jsx
src/pages/About.jsx
src/hooks/useAuth.js
src/utils/api.js
src/styles/globals.css
public/favicon.ico

npx mkstruct react-structure.txt

Express API tree

├── server.js
├── config
│   ├── database.js
│   └── environment.js
├── routes
│   ├── api.js
│   ├── auth.js
│   └── users.js
├── controllers
│   ├── authController.js
│   └── userController.js
├── models
│   └── User.js
├── middleware
│   ├── auth.js
│   └── errorHandler.js
└── utils
    ├── logger.js
    └── validators.js

npx mkstruct backend-tree.txt

Documentation bundle

docs/getting-started.md
docs/api/authentication.md
docs/api/endpoints.md
docs/guides/deployment.md
docs/guides/testing.md
docs/examples/basic.md
docs/examples/advanced.md

Guardrails

• Refuses to write outside the current working directory.
• Creates parent folders before files to avoid partial structures.
• Skips existing files unless --force is supplied.
• Supports dry-runs for safe previews and verbose logging for debugging.

Troubleshooting

Symptom	Cause	Fix
Error: No input provided	No file, --stdin, or -s argument supplied	Provide a filename, pipe stdin, or use -s
Files appear in the wrong place	Ran the command from the wrong directory	pwd, cd into the project root, rerun
Tree format not detected	Non-standard characters or broken indentation	Copy the tree glyphs exactly; run with --verbose for hints
Refusing to write outside CWD	Paths contain .. or absolute segments	Ensure all paths stay relative to the project root

Contributing

• Fork the repo and create a feature branch.
• Install dependencies: npm install.
• Run tests: npm test.
• Open a pull request referencing any related issues.

git clone https://github.com/Gitnaseem745/mkstruct.git
cd mkstruct
npm install
npm test

Bug reports and feature ideas are welcome via GitHub Issues.

License

MIT © Naseem Ansari

See the full text in LICENSE.

Stay in Touch

• GitHub: Gitnaseem745/mkstruct
• npm: mkstruct
• Issue tracker: Report a bug

If mkstruct saves you setup time, consider dropping the repo a ⭐️.

Made with ❤️ by developers, for developers