mkstruct

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

[email protected] 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

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

ASCII tree rules

1. Use the standard characters ├──, └──, and │ (single- or double-dash variants both work).
2. Indent with four spaces or tabs—mkstruct normalizes mixed indentation.
3. 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

1. Fork the repo and create a feature branch.
2. Install dependencies: npm install.
3. Run tests: npm test.
4. 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