Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

usabl init: support monorepos and non-root app directories

Open
  • Is something wrong?
#126 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
45/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
typescript, vite
Domain
testing-qa, tooling

Research direction

Start by reading the usabl init discovery code and the Vite and router lookup paths; the issue names platform/vite.config.ts, framework/vite.config.ts, and the runtime route assembly in platform/main/PlatformRoutes.tsx. Reproduce the empty draft on a monorepo, then check how discovery reports missing routes and empty uiFileGlobs. Done means init produces a usable draft for a named workspace or explains why it refuses and gives the manual next step, while preserving the single-app path.

Written by the indexing model from the issue text.

Description

area: setup enhancement

usabl init assumes a single application at the repository root. On a monorepo it finds neither the Vite config nor the router, writes an empty draft, and leaves the whole config to be hand-authored.

Found while dogfooding on a real second project (#110): ansible/ansible-ui at devel, a PatternFly 6.3.1 monorepo.

What happened

$ usabl init
Wrote usabl.config.json, usabl.routes.json.
Review: no Vite config found; using http://127.0.0.1:5173.
Review: no router file found. Routes sidecar will be empty.
Review: these files are drafts. Merge only after you check routes, globs, and URLs.

The drafts came out with uiFileGlobs: [], surfaces: [], and routes: []. A config in that state resolves to nothing to check, so the gate reports idle on every change.

Why it happened

Two separate assumptions, both reasonable for a single-app repo and both wrong here.

  1. Vite config lookup is root-only. This repo's config is at platform/vite.config.ts, and there is a second one at framework/vite.config.ts. init looked at the root, found nothing, and fell back to the default port. The real dev server runs on 4100 over https, not 5173 over http, so the fallback URL is wrong in three ways at once.

  2. Router discovery expects a static route file. This repo composes routes at runtime from hooks (platform/routes/useGetPlatform*Routes.tsx, assembled in platform/main/PlatformRoutes.tsx), and the path values are relative fragments joined into a tree. There is no file a static reader can parse into absolute URLs.

What it got right

It refused to guess. Every failed inference printed a Review: line naming what it could not determine, and it wrote empty collections rather than inventing routes. A wrong route map would have been worse than a missing one, and the honesty invariant held. This issue is about reach, not about correctness.

Proposed direction

Not a design decision yet, just the options as they look from here.

  • Detect nested Vite configs and, when more than one is found, refuse and print the candidates for the operator to choose rather than picking one.
  • Read the resolved dev server port and protocol from the chosen Vite config instead of assuming the default, since server.port and https are both set explicitly here.
  • Accept an operator-supplied application subdirectory, so usabl init --app platform scopes discovery to one workspace.
  • When routes cannot be derived statically, say so explicitly and point at the manual surface mapping path, rather than writing an empty sidecar that silently reads as idle.
  • Consider whether an empty uiFileGlobs should be a refusal rather than a draft, since the resulting config cannot ever produce a verdict.

Acceptance

  • usabl init on a monorepo either produces a usable draft for a named workspace or refuses with the reason and the manual next step.
  • A config that can never produce a verdict is not written silently.
  • The existing single-app path is unchanged.
Dominant language
TypeScript
Stars
0
Forks
0
Avg merge
2h 48m
Merged PRs (30d)
8

Getting set up

  • No Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from usabl-dev/usabl

All issues in usabl-dev/usabl

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.