Start here - no prior knowledge assumed
A pack is a folder.
This is the rulebook for it.
If you have ever dropped a folder of files into a project and hoped it would get picked up, you already understand the problem packstruct solves. It is one small written rule for what that folder must contain, so every tool agrees - and one command that tells you if you got it right, before anything runs.
What is a "pack", really?
Three plain ideas, no jargon. Everything else on this site is detail on top of these.
1A folder with a label
A pack is just a directory - packs/public/my-thing/. Inside it sits one small file named pack.json that describes the folder: what it is called, a one-line description, and which file inside is the one that "starts" it. That is the whole idea.
2A host that reads it
Something has to notice your folder. That something is a "host" - a program that keeps a list of which packs it loads. Your folder does not run by itself; the host runs it because its list names it. No magic discovery, no surprises.
3A check that says yes or no
Before a host ever touches your folder, one command reads pack.json and tells you if it is correct - in plain words, naming the exact problem. If it says ok, you are done. If it complains, it tells you which field and why.
Your first pack, step by step
Copy this, change the names, run one command. That is the entire beginner path.
# 1. make the folder and its one required file mkdir -p packs/public/hello-pack # 2. describe it - this is the whole contract packs/public/hello-pack/pack.json { "schemaVersion": 1, "name": "hello-pack", # must match the folder name "description": "My first pack", # one short line "version": "1.0.0", "entry": "index.js" # the file that starts it (must exist) } # 3. the entry file the line above names packs/public/hello-pack/index.js # 4. check it. exit 0 means you are done. npx packstruct lint packs/
Four fields do the work: schemaVersion (always 1), name (must equal the folder name), description (a human sentence), and entry (a real file in the folder). There is a fifth, armedByKey, you can ignore until much later.
Prefer to click instead of type? The browser linter checks a pasted pack.json against the same rules, right in this tab - your file never leaves the page.
What the check actually catches
The one mistake that used to cost hours, now caught in a second - before any code runs.
| If you get this wrong | What you see |
|---|---|
| entry names a file that is not there | A named refusal: "entry "index.js" does not exist". Not a deep stack trace three screens into a program you did not write. |
| name does not match the folder | A refusal that names both values, so you fix it in one keystroke. |
| schemaVersion is missing or wrong | A refusal that says the version must be 1. |
| it is all correct | ok and exit code 0. Silence is success; you move on. |
That first row is the whole reason the spec exists. It is the mistake crashtest filed as issue #16, and it is the class packstruct makes impossible to ship by accident.
Where to go next
Pick the door that matches you. Each one assumes only what it says it does.
Just checking a pack
You are done. Run npx packstruct lint packs/ in any project with a packs/ folder. Read the linter page for the flags.
Building on it
Want to write a pack that a host will run, or point a host at your own packs? Go to extend - it assumes you know the basics above and nothing more.
Running a whole fleet
Need one grammar across many repos, with conformance proof and governance? Go to enterprise.
Stuck? That is a bug in the docs.
If a step above did not work, or a word was not defined, tell us - it is the fastest way to make this page better for the next person.