chore: make it easier to get started

Author: danielroe

README.md

@@ -20,13 +20,12 @@ The aim of [npmx.dev](https://npmx.dev) is to provide a better browser for the n
 
 ## Features
 
-- **Dark mode by default** - Easy on the eyes, no toggle needed
-- **Package browsing** - Fast search, package details, READMEs, versions, dependencies
-- **Dependencies view** - Shows regular dependencies and peer dependencies (with optional badges)
-- **User profiles** - View any npm user's public packages at `/~username`
-- **Organization pages** - Browse org packages at `/org/orgname`
-- **Provenance indicators** - Verified build indicators for packages with npm provenance
-- **Admin features** - Org/team management, package access controls via local connector
+- **Dark mode by default** - easier on the eyes
+- **Package browsing** - fast search, package details, READMEs, versions, dependencies
+- **User profiles** - view any npm user's public packages at `/~username`
+- **Organization pages** - browse org packages at `/org/orgname`
+- **Provenance indicators** - verified build indicators for packages with npm provenance
+- **Admin features** - org/team management, package access controls via local connector (coming soon)
 
 ### URL Compatibility
 
@@ -41,15 +40,13 @@ npmx.dev supports npm permalink patterns:
 | `/~<username>` | [`/~sindresorhus`](https://npmx.dev/~sindresorhus) |
 | `/org/<name>` | [`/org/nuxt`](https://npmx.dev/org/nuxt) |
 
-**Coming soon** (with local connector): `/package/<name>/access`, `/package/<name>/collaborators`, `/settings/*`
-
 ## Tech Stack
 
-- [Nuxt 4](https://nuxt.com/) - Vue framework
-- [Nitro](https://nuxt.com/docs/guide/concepts/server-engine) - Server engine with API routes
-- [UnoCSS](https://unocss.dev/) - Atomic CSS engine
-- [nuxt-og-image](https://github.com/nuxt-modules/og-image) - Dynamic OG images
-- [npm Registry API](https://github.com/npm/registry/blob/main/docs/REGISTRY-API.md) - Package data
+- [Nuxt 4](https://nuxt.com/)
+- [Nitro](https://nuxt.com/docs/guide/concepts/server-engine)
+- [UnoCSS](https://unocss.dev/)
+- [nuxt-og-image](https://github.com/nuxt-modules/og-image)
+- [npm Registry API](https://github.com/npm/registry/blob/main/docs/REGISTRY-API.md)
 
 ## Try it out locally
 
@@ -86,6 +83,21 @@ pnpm test:browser
 pnpm test:types
 ```
 
+### Local Connector (CLI)
+
+The `cli/` workspace contains a local connector that enables authenticated npm operations from the web UI. It runs on your machine and uses your existing npm credentials.
+
+```bash
+# run the connector in dev mode
+pnpm --filter @npmx/connector dev
+
+# or build and run the production version
+pnpm --filter @npmx/connector build
+node cli/dist/cli.mjs
+```
+
+The connector will check your npm authentication, generate a connection token, and listen for requests from npmx.dev.
+
 ## License
 
 Made with ❤️

cli/package.json

@@ -18,8 +18,8 @@
   ],
   "scripts": {
     "build": "unbuild",
-    "dev": "tsx src/cli.ts",
-    "typecheck": "tsc --noEmit"
+    "dev": "node --experimental-strip-types src/cli.ts",
+    "test:types": "tsc --noEmit"
   },
   "dependencies": {
     "@clack/prompts": "1.0.0-alpha.9",
@@ -32,8 +32,7 @@
     "picocolors": "^1.1.1"
   },
   "devDependencies": {
-    "@types/node": "^25.0.10",
-    "tsx": "^4.21.0",
+    "@types/node": "^24.10.9",
     "typescript": "^5.9.3",
     "unbuild": "^3.6.1"
   }

cli/src/cli.ts

@@ -2,9 +2,9 @@
 import { defineCommand, runMain } from 'citty'
 import { listen } from 'listhen'
 import { toNodeListener } from 'h3'
-import { createConnectorApp, generateToken, CONNECTOR_VERSION } from './server'
-import { getNpmUser } from './npm-client'
-import { initLogger, showToken, logInfo, showAuthRequired } from './logger'
+import { createConnectorApp, generateToken, CONNECTOR_VERSION } from './server.ts'
+import { getNpmUser } from './npm-client.ts'
+import { initLogger, showToken, logInfo, showAuthRequired } from './logger.ts'
 
 const DEFAULT_PORT = 31415
 

cli/src/index.ts

@@ -1,2 +1,2 @@
-export * from './types'
-export { createConnectorApp, generateToken } from './server'
+export * from './types.ts'
+export { createConnectorApp, generateToken } from './server.ts'

cli/src/npm-client.ts

@@ -1,6 +1,6 @@
 import { exec } from 'node:child_process'
 import { promisify } from 'node:util'
-import { logCommand, logSuccess, logError } from './logger'
+import { logCommand, logSuccess, logError } from './logger.ts'
 
 const execAsync = promisify(exec)
 

cli/src/server.ts

@@ -8,7 +8,7 @@ import type {
   PendingOperation,
   OperationType,
   ApiResponse,
-} from './types'
+} from './types.ts'
 import {
   getNpmUser,
   orgAddUser,
@@ -26,7 +26,7 @@ import {
   ownerAdd,
   ownerRemove,
   type NpmExecResult,
-} from './npm-client'
+} from './npm-client.ts'
 
 // Read version from package.json
 const __dirname = dirname(fileURLToPath(import.meta.url))

cli/tsconfig.json

@@ -1,15 +1,20 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
+    "module": "nodenext",
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
-    "outDir": "dist",
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
     "declaration": true,
     "declarationMap": true
   },
-  "include": ["src/**/*.ts"],
-  "exclude": ["node_modules", "dist"]
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
 }