sm new should scaffold host + a working sample module in a uv/npm workspace, matching the framework repo's own layout

[antosubash]

Summary

uvx --from simple_module_cli sm new my-app (0.0.7) scaffolds a flat host application: a single directory containing main.py, client_app/, migrations/, etc., depending on wheel-installed modules only. There's no modules/ directory, no sample module, and no workspace plumbing. The result is an app that can run the bundled auth/users/dashboard/permissions modules but offers no template for adding a new module — which is the framework's whole point.

The framework repo itself uses a much richer layout that's already battle-tested for module development. sm new should produce a scaled-down version of that shape.

Current sm new output

my-app/
├── .env.example
├── .gitignore
├── Makefile
├── README.md
├── alembic.ini
├── client_app/
│ ├── app.tsx
│ ├── main.tsx
│ ├── package.json # standalone, not a workspace
│ ├── pages/
│ ├── tsconfig.json
│ └── vite.config.ts
├── main.py # host entry — at the root
├── migrations/
├── package.json # weirdly empty top-level pkg.json (?)
├── pyproject.toml # only references wheel-installed modules
└── templates/

pyproject.toml lists only wheel deps, no [tool.uv.workspace]. Top-level package.json has no workspaces field. There is nowhere for a user-authored module to live, and nothing showing them how a module is wired up (Python entry-point, FE peer deps, page registration).

Framework repo's own layout (reference)

From a gh api repos/antosubash/simple_module_python/contents/... walk:

simple_module_python/
├── package.json # workspaces: ['host/client_app', 'packages/*', 'modules/*']
├── pyproject.toml # [tool.uv.workspace] members = ['framework/*', 'modules/*', 'host']
├── host/
│ ├── pyproject.toml # depends on simple_module_hosting + chosen modules via [tool.uv.sources] workspace=true
│ ├── main.py
│ ├── client_app/
│ ├── alembic.ini
│ ├── migrations/
│ ├── routes.py
│ ├── routes_i18n.py
│ ├── templates/
│ └── tests/
├── modules/
│ ├── auth/
│ │ ├── pyproject.toml # entry_points.simple_module, hatch.force-include for package.json
│ │ ├── package.json # peerDependencies: react, react-dom, @inertiajs/react, @simple-module-py/ui
│ │ ├── auth/ # the Python package
│ │ │ ├── __init__.py
│ │ │ ├── module.py # AuthModule class registered via entry_points
│ │ │ ├── contracts/
│ │ │ ├── deps.py
│ │ │ └── locales/
│ │ ├── tests/
│ │ ├── README.md
│ │ └── LICENSE
│ ├── dashboard/ # same shape
│ ├── users/
│ └── ...
├── packages/ # npm-only workspaces (UI / i18n / tsconfig)
│ ├── ui/
│ ├── i18n/
│ └── tsconfig/
└── framework/ # the framework's own Python packages
 ├── core/
 ├── db/
 ├── hosting/
 ├── cli/
 └── testing/

This layout already solves several things sm new currently leaves broken or unclear:

• uv workspace ([tool.uv.workspace] members = ['modules/*', 'host']) lets a user iterate on a custom module against the host without publishing.
• npm workspace (workspaces: ['host/client_app', 'packages/*', 'modules/*']) puts the host's client_app/ and every module's frontend assets into a single dependency graph — vite finds module .tsx files and their JS deps without symlinks (this is the right answer to the closed Module-shipped .tsx pages need symlink + vite aliases + inline tsconfig boilerplate #73's symlink-and-alias workaround).
• A module template to copy. The first thing anyone building on the framework wants to do is add a feature module. Today they have to reverse-engineer the wheel-installed auth//users/ packages out of .venv/site-packages/.

Proposed change

sm new my-app should produce something like:

my-app/
├── package.json # workspaces: ['host/client_app', 'modules/*']
├── pyproject.toml # [tool.uv.workspace] members = ['host', 'modules/*']
├── Makefile # delegates to host/, runs sync-js-deps + gen-pages
├── host/
│ ├── pyproject.toml # the previous root pyproject moved here
│ ├── main.py
│ ├── client_app/
│ │ ├── package.json # workspace member
│ │ ├── vite.config.ts
│ │ └── ... (existing host client app contents)
│ ├── alembic.ini
│ ├── migrations/
│ └── templates/
└── modules/
 └── hello/ # ONE end-to-end example module
 ├── pyproject.toml # entry_points.simple_module, depends on simple_module_core
 ├── package.json # peerDependencies: react, @simple-module-py/ui
 ├── hello/
 │ ├── __init__.py
 │ ├── module.py # HelloModule(MetaBase): name='Hello', register_routes/menu/permissions
 │ ├── routes.py # one HTTP route (e.g. GET /hello -> Inertia render)
 │ └── pages/
 │ └── Hello.tsx # the page rendered by the route
 └── tests/
 └── test_hello.py # passing pytest hitting the endpoint

The sample module should:

• Boot cleanly when make dev is run on the freshly-scaffolded project.
• Add a sidebar/menu entry, so the user sees their module register in the running app.
• Demonstrate the three things a module always wires: a route, a permission, a page.
• Use the same entry_points.simple_module mechanism the bundled modules use, so the same registration story works whether the module is workspace-local or pip-installed later.
• Have a pyproject.toml shaped like modules/auth/pyproject.toml in the framework repo (hatchling build, [tool.hatch.build.targets.wheel.force-include] for package.json, [project.entry-points.simple_module]).

The CLI should expose flags for the workspace mode:

• sm new my-app → workspace mode (default, scaffolds host + sample module).
• sm new my-app --flat → today's behavior (single host, no modules dir) for users who only want to consume published modules.
• sm create-module <name> (already present in 0.0.7) should default to writing to modules/<name>/ when run inside a workspace, instead of the current cwd.

Why this matters

This isn't just a structural nicety — several of the open frontend issues compound from the lack of a workspace:

• @simple-module-py/ui exports map ('.', './*') doesn't cover ./components/*, ./layouts/* — vite can't resolve subpath imports from module pages #110, @simple-module-py/ui exports map: './*': './src/*' can't resolve nested subpaths or extension-less imports #115 (exports map): consumed-from-wheel .tsx files break module-resolution. A workspace pulls module .tsx into the npm tree and vite resolves them naturally.
• Module wheels declare empty 'dependencies' but their .tsx imports lucide-react/sonner directly; Makefile never runs sm host sync-js-deps #116 (sync-js-deps not wired): the workspace's npm workspaces field auto-installs every module's deps; sync-js-deps becomes optional.
• Module-shipped .tsx pages need symlink + vite aliases + inline tsconfig boilerplate #73 (closed; symlinks-and-aliases): the workspace removes the need entirely.

All three problems converge on the same fix as soon as the host + modules live in one workspace.

Reference files in the framework repo

• Top-level workspace config: pyproject.toml, package.json at repo root.
• A canonical module: modules/auth/{pyproject.toml,package.json,auth/module.py}.
• A canonical host: host/{pyproject.toml,main.py,client_app/}.

Mirroring those (with the bundled wheels as workspace deps via [tool.uv.sources] = { workspace = true } for the source case, or PyPI versions for the pure-consumer case) gets sm new to a layout where users have a real on-ramp to authoring modules.

Related

• @simple-module-py/ui exports map ('.', './*') doesn't cover ./components/*, ./layouts/* — vite can't resolve subpath imports from module pages #110 / @simple-module-py/ui exports map: './*': './src/*' can't resolve nested subpaths or extension-less imports #115 / Module wheels declare empty 'dependencies' but their .tsx imports lucide-react/sonner directly; Makefile never runs sm host sync-js-deps #116 — frontend resolution problems that mostly disappear under a workspace.
• Module-shipped .tsx pages need symlink + vite aliases + inline tsconfig boilerplate #73 (closed) — the original symlink-workaround report that this enhancement supersedes.
• The CLI already has sm create-module — that command's intended target dir presumably is modules/<name>/, which only exists if sm new set up the workspace first.

Environment

• simple_module_cli 0.0.7

[antosubash]

Update after triaging 0.0.8 — this issue is the keystone

Verified against simple_module_cli==0.0.8 + bumping npm/python pins to 0.0.8 (per #119). The npm-package-side issues (#114, #115) are actually fixed in @simple-module-py/ui@0.0.8. But make dev still doesn't work because:

• Module .tsx files live in .venv/lib/python3.12/site-packages/<mod>/pages/....
• Vite's resolver, walking up from those files, never sees client_app/node_modules (it's a sibling of the venv, not an ancestor).
• All bare imports — lucide-react, sonner, @simple-module-py/ui/components/ui/button, etc. — fail with "could not be resolved" despite the host having installed them correctly.

A targeted alias-block in vite.config.ts works around it (see #116's update), but that's a stopgap with a maintenance tail (every new bare import needs another alias entry) and doesn't survive once a user adds their own module.

The framework repo's own layout — host/, modules/<m>/, packages/<m>/ all in one npm workspace via the root package.json's workspaces field — solves this naturally:

• Module .tsx files are workspace members, so vite's normal walk-up resolution finds the hoisted node_modules at the workspace root.
• No aliases needed.
• No sync-js-deps Makefile step needed (Module wheels declare empty 'dependencies' but their .tsx imports lucide-react/sonner directly; Makefile never runs sm host sync-js-deps #116 part B becomes optional).
• Adding a custom module is cp -r modules/<sample> modules/<myname> plus an entry-point — instead of "reverse-engineer wheels out of .venv/".

So this issue stops being just an ergonomic nicety: with #114/#115 closed and the alias hack as the only alternative, scaffolding into a workspace is the load-bearing fix.

Concrete proposal (refined)

Same shape as the original post, plus the explicit consequence that sm new ends up at a working make dev without any frontend manual fixes:

my-app/
├── package.json # workspaces: ['host/client_app', 'modules/*']
├── pyproject.toml # [tool.uv.workspace] members = ['host', 'modules/*']
├── Makefile # make dev → cd host && make dev
├── host/
│ ├── pyproject.toml # depends on simple_module_hosting + chosen modules (workspace = true for any local ones)
│ ├── main.py
│ ├── client_app/ # workspace member; vite root
│ │ ├── package.json # depends on @simple-module-py/ui (workspace pkg if pinned to local), react, etc.
│ │ ├── vite.config.ts # NO custom aliases needed — workspace hoist handles resolution
│ │ └── ...
│ ├── alembic.ini
│ ├── migrations/
│ └── templates/
└── modules/
 └── hello/ # one working sample module
 ├── pyproject.toml # entry_points.simple_module = \"hello.module:HelloModule\"; hatch.force-include = package.json
 ├── package.json # peerDependencies: react, @simple-module-py/ui
 ├── hello/
 │ ├── __init__.py
 │ ├── module.py # registers route + permission + menu item
 │ ├── routes.py
 │ └── pages/
 │ └── Hello.tsx # imports from @simple-module-py/ui — resolves via workspace
 └── tests/

The Hello page should use @simple-module-py/ui/components/PageShell and @simple-module-py/ui/components/ui/button so the very-first make dev exercises the same import shapes the bundled modules use — meaning anyone scaffolding a host immediately sees a working module render at, say, http://localhost:8000/hello.

Suggested CLI shape

• sm new my-app → workspace mode (default).
• sm new my-app --flat → today's flat shape (kept as opt-in for users who only consume published modules and don't want modules/).
• sm create-module <name> → writes to modules/<name>/ if invoked inside a workspace; else current dir.

Why I'm flagging it as the keystone

Counting open issues that this would close or sharply de-prioritize:

• Module wheels declare empty 'dependencies' but their .tsx imports lucide-react/sonner directly; Makefile never runs sm host sync-js-deps #116 (sync-js-deps + Makefile wiring) — workspace handles JS deps via npm hoist; sync-js-deps becomes a niche tool for non-workspace consumers.
• sm new scaffold pins ^0.0.3 npm deps and ==0.0.7 python deps even when 0.0.8 is published; npm caret on 0.0.x silently blocks the bump #119 (stale pins / caret-on-0.0.x) — partially: workspace-internal deps use * in package.json and pyproject [tool.uv.sources] = { workspace = true }, sidestepping pin staleness entirely. (External pins still need to be kept fresh — that part of sm new scaffold pins ^0.0.3 npm deps and ==0.0.7 python deps even when 0.0.8 is published; npm caret on 0.0.x silently blocks the bump #119 stays.)
• The closed Module-shipped .tsx pages need symlink + vite aliases + inline tsconfig boilerplate #73 — explicitly: workspace removes the symlink-and-alias workaround.
• This issue (sm new should scaffold host + a working sample module in a uv/npm workspace, matching the framework repo's own layout #117) — the original on-ramp gap.

That's 3 active issues collapsed into one structural change, with the bonus that it matches the framework's own dev experience.

[antosubash]

Update — workspace shape now ships in sm new, with caveats

The 0.0.8 release of simple_module_cli added a lot of what this issue asked for:

✅ sm new now scaffolds:

• A workspace-root pyproject.toml with [tool.uv.workspace] members = [\"modules/*\"].
• A workspace-root package.json with \"workspaces\": [\"client_app\", \"modules/*\"].
• A sample modules/hello/ module (Python + JS package + entry_point + endpoints + pages dir).
• [tool.uv.sources.simple_module_hello] workspace = true so the host pulls hello from the local workspace.
• Makefile with sync-js-deps wired into install.

⚠️ But the workspace shape is flat (client_app/ and modules/ as siblings of the worktree root), not nested under host/ like the framework repo. That trips a separate framework bug (#129 — sync-js-deps hardcodes client_app.parent.parent which is wrong for the flat shape).

⚠️ And the sample module + new scaffold ships with several gating bugs that prevent a fresh make install from working at all:

• sm new sample module pins simple_module_core/db/hosting>=1.0,<2.0 — uv sync fails because framework is at 0.0.x #126 — modules/hello/pyproject.toml pins simple_module_*>=1.0,<2.0 against a 0.0.x framework
• sm new sample module's [tool.hatch.build.targets.wheel.force-include] requires hello/static/dist/ — uv sync fails because that dir is gitignored #127 — modules/hello/pyproject.toml force-include requires static/dist/ which doesn't exist on a fresh scaffold
• sm new root package.json pins @inertiajs/react ^1.0.0 but @simple-module-py/ui@0.0.8 peers ^2.0.0 — npm install fails ERESOLVE #128 — root package.json pins @inertiajs/react: ^1.0.0 but the ui package peers ^2.0.0
• sync-js-deps assumes host/client_app/ layout (parent.parent walk) — fails ENOENT on flat sm new scaffold #129 — sync-js-deps heuristic walks up too far in the flat layout

After fixing those locally, make install + make migrate + make dev produces a working stack:

• API boots: Loaded 6 module(s): Auth, Hello, Settings, Users, Dashboard, Permissions (77 + Hello's routes = 79 routes)
• Vite boots clean — no "could not be resolved" errors, no aliases needed in vite.config.ts

So the workspace structure DID solve the resolver issue this issue predicted it would. The remaining failures are scaffold-content bugs, not architectural.

What's still on the original wishlist

• host/ subdirectory. The framework repo has <repo>/host/client_app/; the scaffold has <repo>/client_app/. The latter works for the npm-resolution case, but it's incongruent with the framework's docs and breaks sync-js-deps (sync-js-deps assumes host/client_app/ layout (parent.parent walk) — fails ENOENT on flat sm new scaffold #129). Worth aligning to host/client_app/.
• The sample module exercising the UI. modules/hello/hello/pages/ is empty (.gitkeep only). A fresh make dev doesn't show the user a Hello page rendering with @simple-module-py/ui components — which was the value of the sample. Worth adding a pages/Index.tsx and a route that renders it via Inertia.
• sm create-module writing to modules/. Not verified yet; should become trivial once the workspace shape is the default.

This issue can probably stay open as a tracker for those three remaining items, and the four bugs above should resolve independently.