npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

create-stellaris-mod

v0.8.0

Published

Scaffold a Stellaris mod project that builds with @pdx-ts/sdk

Readme

create-stellaris-mod

create-stellaris-mod scaffolds Stellaris mod projects for @pdx-ts/sdk. It can also inspect a built-in Recipe Catalog and add curated Feature source to an existing project.

The CLI produces source code the author owns. It is not a runtime dependency of the generated mod.

Requirements and quick start

The CLI requires Node.js 22 or newer. Generated projects require Node.js 22.18 or newer because their scripts execute erasable TypeScript directly.

npx create-stellaris-mod my-mod
cd my-mod

npm run inspect
npm test
npm run build
npm run install-mod

create-stellaris-mod my-mod is an alias for the canonical command:

npx create-stellaris-mod init my-mod

The CLI finds the local Stellaris installation when possible and reads the game version from launcher-settings.json. A supported three-part version selects the matching identifier package; missing or unsupported version data falls back to the build this scaffolder was verified against. The generated project typechecks, tests, and builds after installation.

First five minutes

  1. Edit the mod name, version, tags, or supported game version in stellaris-mod.json.
  2. Open src/features/example.ts to see a technology, event, and on-action hook in one Feature, and src/features.ts to see the line that puts it in the mod.
  3. Run npm run inspect to review Feature stems, Item ids, dependency versions, vanilla evidence, patch plans, and warnings as deterministic YAML.
  4. Run npm test to execute the example event chain without launching the game.
  5. Run npm run build to write out/, or npm run install-mod to place the built mod where the launcher expects it.

The generated README repeats these project-specific commands and records the game-version pin chosen during scaffolding. The commands above assume the npm default; the generated README, AGENTS.md, and the terminal next steps all spell them with the package manager --pm selected, so a pnpm or Bun project is never told to run npm install.

Commands

init

Create a new project:

npx create-stellaris-mod init my-mod

The destination must not already exist, even as an empty directory. The planner resolves every prompt before publication, and cancellation leaves the target unchanged.

list

List the recipes included in this release:

npx create-stellaris-mod list

view

Describe a recipe, its generated topology, its questions, and the flags that answer those questions without prompting:

npx create-stellaris-mod view technology

generate

Write one Feature source file into an existing project and declare it in the Feature list:

npx create-stellaris-mod generate technology "Resonance Theory"

generate searches upward for stellaris-mod.json, checks for a string package.json#imports.#mod mapping and a supported SDK range, writes src/features/resonance_theory.ts, and appends one line to src/features.ts:

export { feature as resonanceTheory } from "./features/resonance_theory.ts";

It never overwrites an existing file, directory, or symlink, and it never creates or rewrites src/features.ts: the list must already exist as a regular file, and a list that already declares the module's path or already exports the binding is refused with the line number. The module is written first; if the append then fails, the module is removed again, so the project never holds a feature module its list does not name. --dry-run prints the exact source and the line it would append without creating directories or files. A successful normal run writes only the created path to stdout; the appended line is reported on stderr.

Publication holds the destination directory and temporary file open while it checks their identity before and after creating the final hard link. Node does not expose descriptor-relative openat or linkat, so pathname publication cannot guarantee containment against a hostile process that concurrently replaces project directories. Do not generate while an untrusted process can rename project directories.

Generated project

my-mod/
|-- stellaris-mod.json         Project Manifest and mod identity
|-- stellaris-mod.schema.json  local editor schema
|-- package.json
|-- tsconfig.json
|-- vitest.config.ts
|-- knip.json                  the dead-file check behind `npm run lint`
|-- eslint.config.js           omitted with --no-eslint
|-- .prettierrc                omitted with --no-prettier
|-- assets/                    create when the first Asset is needed
`-- src/
    |-- mod.ts                 createModProject: project, config, and mod
    |-- build.ts               buildTheMod, the one Fold every command shares
    |-- features.ts            the Feature list: one line per Feature
    |-- index.ts               render and write out/
    |-- inspect.ts             Fold and print deterministic YAML
    |-- install.ts             build and install for the launcher
    |-- vanilla.ts             parsed install, when one was found
    |-- flags.ts               shared typed values
    `-- features/
        |-- example.ts         named Feature export
        `-- example.test.ts    colocated mod-logic test

Agent support files are also generated by default and are described separately below.

Project Manifest and build pipeline

stellaris-mod.json is the single author-owned source of truth for mod identity, launcher metadata, and the Asset tree. Its mod object contains exactly one key, the mod prefix:

{
  "$schema": "./stellaris-mod.schema.json",
  "mod": {
    "my_mod": {
      "name": "My Mod",
      "version": "0.1.0",
      "supportedVersion": "4.4.*",
      "tags": []
    }
  },
  "assetsDirectory": "assets"
}

The object key preserves the prefix as a TypeScript literal. assetsDirectory mirrors opaque files into the built mod root. Feature source is not in the manifest: src/features.ts, the Feature list, declares it.

The generated package maps #mod to ./src/mod.ts. Feature modules import the capability through that stable alias instead of computing relative paths.

Importing mod.ts does not compile or touch disk, and it imports nothing else of the project: feature modules import it, so a static import of the Feature list from mod.ts would evaluate them before mod exists. src/build.ts is the module that imports both sides, and its buildTheMod() owns the conventional sequence:

validate manifest
  -> create immutable capability
  -> import the Feature list as a namespace
  -> load vanilla view when configured
  -> capture Assets
  -> Fold once, over exactly the declared Features

The build, inspect, and install commands call that same sequence and then add their one final operation. A custom project can compose the SDK's lower-level interfaces directly.

The Feature list is the only thing that puts a module in the mod, so a module under src/features/ that no line names is dead code that still compiles and passes its tests. npm run lint runs knip with only two reports on, unused files and unresolved imports, and reports such a module by path. Every other knip report is off in knip.json: unused exports are the norm in a feature module, and the vitest plugin is disabled so a module reachable only through its own test does not pass the check.

src/vanilla.ts returns no view in exactly two cases: PDX_NO_VANILLA=1, and the SDK finding no install on its own. Every other failure — an unreadable game directory, a game whose shape the parser does not recognize, a corrupt archive — propagates and the build reports it. An unexpected failure is not evidence that there is no game, and a build that silently drops id-collision checks, version evidence, and patch sources cannot be told apart from one that kept them.

A STELLARIS_PATH that is not a game root propagates too, matching the CLI's own rule that an explicit invalid path is fatal. A path baked in by scaffolding is treated the opposite way: it records one machine rather than requesting anything here, so a checkout where it does not resolve still builds without the view.

Recipe Catalog

Recipes generate short, working TypeScript starters. An Item recipe emits one Feature containing one Item. A Feature recipe coordinates several Items when a useful example needs event chains, references, or shared script.

Recipe questions cover structural intent: topology, scope contracts, control flow, authoring kind, and cross-Item relationships. Values that are easier to edit in source are left in source instead of becoming prompts.

Each recipe owns a pure renderer from validated answers to one source file. The Catalog does not derive templates by walking SDK field metadata, and it does not create a second authoring schema.

With --yes, or when stdin is not a terminal, generate requires the recipe id and name and uses every recipe default. view <recipe> lists all available question flags.

Install discovery and version pinning

The CLI uses --stellaris-path first, then STELLARIS_PATH, then the platform's normal Steam locations. A missing automatically detected install is not fatal: the project still writes src/vanilla.ts, which finds the install later if one appears, and pins identifiers to the Stellaris build this scaffolder was verified against.

An explicit invalid --stellaris-path is fatal. Treating a misspelled path as a request to disable install checks would hide user intent.

The generated dependency range has the form:

"@pdx-ts/stellaris-ids": ">=4.4.6-0 <4.4.6"

It selects the newest package revision for one exact game build. Immediately after a Stellaris update, the matching npm release may not exist. The CLI reports that case and asks the author to wait for the release or choose a game build that has one.

Safety and automation

Every configurable init prompt has a flag. The target directory remains a positional argument. For generate, recipe questions have flags while the recipe id and generated name remain positional. --yes, or non-terminal stdin, accepts defaults without waiting for input and requires those positionals.

--name <string>
--prefix <snake_case>
--stellaris-path <path>
--supported-version <v4.4.*>
--tags <a,b>
--local <path>
--pm <command>  # npm, pnpm, yarn, and bun are the detected common cases
--dry-run
-y, --yes
--no-prettier
--no-eslint
--no-llm
--no-git
--no-install

Generation-specific flags are:

--cwd <path>
--yes
--dry-run
--allow-unsupported-sdk

--allow-unsupported-sdk changes one compatibility refusal into a warning. It does not load the SDK, weaken the generated code, or promise that a later build will pass.

On platforms where symlink creation returns EPERM, publication falls back to regular file and directory copies. This keeps the default project usable on Windows without symbolic-link privileges.

Optional agent support

The default project includes shared AGENTS.md guidance, project-scoped skills, and Codex and Claude definitions for an SDK documentation expert. All files stay inside the generated project; initialization does not edit user-level agent configuration or download external skills.

The generated agent instructions tell the documentation expert to compare the project's SDK dependency with documentation provenance before giving API advice. This is an agent workflow instruction, not a separate compatibility checker in the CLI.

AGENTS.md carries the second half of that comparison in its Documentation provenance section: the @pdx-ts/sdk range the project was scaffolded against, and the SDK source revision behind it. The documentation site publishes the same hash as the SDK revision: line in its llms.txt, so the two agree exactly when the fetched documentation was generated from the SDK source this project was scaffolded against. It records one moment rather than checking continuously: once the project declares a version outside that range, the recorded revision describes an older SDK and the version match governs alone.

A project scaffolded with --local records no provenance and says so. Its @pdx-ts/sdk is a file: link at a checkout, which is neither a published version nor a fixed revision, so there is nothing for published documentation to match. Recording the release coordinates anyway would point the documentation expert at a version the project does not depend on.

Use --no-llm to omit the complete bundle.

Local SDK development

Point --local at an unreleased repository checkout to scaffold a consumer against local packages:

npm run build  # in the pdx-sdk checkout first
npx create-stellaris-mod my-mod --local ~/code/pdx-sdk

The project receives file: dependencies. Build the checkout first because an external project resolves published dist/ exports. The monorepo's internal pdx-source condition is deliberately not part of the consumer contract.

Implementation

The published CLI is compiled TypeScript and ESM. It uses @clack/prompts for interactive terminals and semver for dependency compatibility. Generated projects use strict TypeScript, Vitest, optional ESLint and Prettier, JSON Schema validation, and the selected package-manager command.

The public module exports main, processIo, CliIo, and detectPackageManager. main(argv, io, terminal) returns an exit code and uses injected I/O, which lets tests run the complete command router without calling process.exit.

Internally, resolution and publication are separate:

CLI arguments and prompts
  -> resolved configuration
  -> pure scaffold or recipe plan
  -> exclusive filesystem publication
  -> optional package installation and git initialization

src/plan.ts returns a map of regular files and relative symlinks without touching disk. Recipe renderers are also pure. The filesystem layer publishes only after validation succeeds.

Development and verification

Run from the repository root:

npm run scaffold -- --help
npm run scaffold -- --dry-run --yes /tmp/demo
npm run typecheck
npm test
npm run build

The end-to-end scaffold test creates a temporary project and runs its real typecheck, lint, build, and tests. This is the main guard against invalid TypeScript inside string templates, and it proves knip resolves #mod and the .ts imports the way Node and TypeScript do. Unit tests cover pure plans, option parsing, command routing, Recipe variants, safety refusals, and cross-platform publication.

See the Scaffolding glossary for Recipe and Project Manifest terminology.