Skip to content

feat: improve skill scores for nitro #4116

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
popey wants to merge 1 commit into
base: main
Choose a base branch
from
+75 −31
Open

feat: improve skill scores for nitro #4116

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 23 additions & 27 deletions .agents/skills/update-deps/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,17 @@
# Update Dependencies Skill
---
name: update-deps
description: >
Update and audit dependencies in the Nitro monorepo using pnpm. Handles non-major upgrades,
pre-release version tracking, workspace link-reference fixes, and lockfile regeneration.
Use when upgrading packages, checking for outdated dependencies, fixing version conflicts,
or preparing a dependency-update PR in this repository.
---

This skill guides you through the process of updating dependencies in the Nitro repository.
# Update Dependencies

## Step-by-Step Process

### Ensure Clean State

Check that you're on a clean main branch with latest changes.

- Clean working directory on main branch
- Latest changes pulled from remote
### 1. Ensure Clean State

```bash
git checkout main
Expand All @@ -19,19 +21,15 @@ git status # Should show "nothing to commit, working tree clean"

(if branch name starts with chore, you can stay in it, no need to pull or change branch or clean state)

### Initial Install

Run an initial install to ensure everything is up to date:
### 2. Initial Install

```bash
pnpm install
```

### Run pnpm upgrade -r

Run `pnpm upgrade -r` to update non-major versions.
### 3. Run pnpm upgrade -r

After upgrade, check git diff:
Run `pnpm upgrade -r` to update non-major versions. After upgrade, check git diff:

- Make sure range types does not change in `dependencies` field (example: `"h3": "^2.0.1-rc.7"` should remain `"h3": "^2.0.1-rc.7",` not `"h3": "2.0.1-rc.7",`)
- Make sure dependencies are not converted to `link:..` (example: `"nitro": "latest",` should remain same, instead of `"nitro": "link:../.."`)
Expand Down Expand Up @@ -63,9 +61,9 @@ done

If any dependencies in root `package.json` lost their `^` prefix, restore them manually.

### Check for Outdated Dependencies
**CHECKPOINT**: Verify `git diff` shows no `link:` conversions and no dropped `^` prefixes before continuing.

Find outdated dependencies:
### 4. Check for Outdated Dependencies

```bash
pnpm outdated -r
Expand All @@ -87,19 +85,19 @@ Or check all versions for a specific package:
pnpm show <package-name> versions
```

### 4. Update Dependencies
### 5. Update Dependencies

Manually update all dependencies to their latest versions in [package.json](../package.json):

- Update both `dependencies` and `devDependencies`
- Keep the range prefix (e.g., `^` for caret ranges)
- **For beta/alpha/rc packages**: Update to the latest pre-release tag found in step 3
- **For beta/alpha/rc packages**: Update to the latest pre-release tag found in step 4
- Example: `vite: "8.0.0-beta.6"` → `"8.0.0-beta.7"`
- Example: `h3: "^2.0.1-rc.7"` → `"^2.0.1-rc.8"` (if available)
- Maintain version range conventions (prefer `^` over exact versions)
- **Do not update** `@azure/functions`

### 5. Clean Install
### 6. Clean Install

Remove lock file and node_modules, then reinstall:

Expand All @@ -108,22 +106,20 @@ rm -rf node_modules pnpm-lock.yaml
pnpm i
```

### 6. Lint and Fix

Run linting and auto-fix issues:
### 7. Lint and Fix

```bash
pnpm format
```

### 7. Build Project

Build the project to ensure compatibility:
### 8. Build Project

```bash
pnpm build
```

**CHECKPOINT**: Build must succeed before continuing. If it fails, see Common Issues below.

### 9. Fix Remaining Issues

If there are lint or type errors:
Expand All @@ -133,7 +129,7 @@ If there are lint or type errors:
3. Re-run `pnpm format` to verify lint fixes
4. Re-run `pnpm typecheck` to verify type fixes. Ignore errors, only report them in the end.

### 10. Final
### 10. Summary

Do not commit changes. Only summarize what happened.

Expand Down
56 changes: 52 additions & 4 deletions skills/nitro/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,58 @@
---
name: nitro
description: Build and deploy universal JavaScript servers with Nitro
description: >
Build and deploy universal JavaScript servers using Nitro, an H3-powered framework with
deployment presets for Vercel, Cloudflare Workers, Deno, Bun, and more. Create API routes,
middleware, server plugins, scheduled tasks, and WebSocket handlers. Use when working with
Nitro projects, creating server endpoints, configuring deployment presets, debugging H3
handlers, or building serverless/edge backends.
---

@docs/TOC.md

You can use `npx nitro docs [--page <path>] [...args]` to explore the documentation locally.
For example, `npx nitro docs --page /docs/routing` will open the routing page of the guide section.
If not available, fallback to https://nitro.build/llms.txt
## Quick Reference

Explore documentation locally or fall back to the hosted version:

```bash
# Browse docs by topic
npx nitro docs --page /docs/routing

# Full docs index
npx nitro docs
```
Comment on lines +17 to +23
Copy link

@coderabbitai coderabbitai bot Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Check which Nitro CLI commands are documented and valid

# Search for CLI command references in the repository
echo "=== Searching for nitro CLI command patterns ==="
rg -n "npx nitro(?:pack)?\b" --type md -C2

echo -e "\n=== Checking package.json for bin entries ==="
fd -e json "^package\.json$" --exec jq -r 'select(.bin != null) | "File: \(.name // "unknown")\nBin entries: \(.bin)"' 2>/dev/null

Repository: nitrojs/nitro

Length of output: 1454

🏁 Script executed:

# Check if nitropack is a separate dependency or an old name
rg "nitropack" --type json -A 2 -B 2

# Check the package.json to see all dependencies
fd -e json "^package\.json$" -x head -50 {}

# Look for any documentation or comments about nitropack
rg "nitropack" --type md -A 2 -B 2 | head -50

Repository: nitrojs/nitro

Length of output: 12373

Update CLI commands: change npx nitropack to npx nitro in Common Tasks section.

Lines 43, 49, and 55 use npx nitropack, but Nitro v3 renamed the package from nitropack (v2) to nitro (v3). These should be changed to npx nitro dev, npx nitro build, and NITRO_PRESET=cloudflare-pages npx nitro build respectively, to match the Quick Reference section (lines 19, 22) and align with the current CLI.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@skills/nitro/SKILL.md` around lines 17 - 23, In the Common Tasks section
replace the deprecated "npx nitropack" invocations with the updated Nitro v3
CLI: change the snippet that runs the dev server from "npx nitropack" to "npx
nitro dev", change the build command from "npx nitropack" to "npx nitro build",
and change the Cloudflare Pages build invocation from "npx nitropack build" to
"NITRO_PRESET=cloudflare-pages npx nitro build"; locate the three occurrences by
searching for the string "npx nitropack" in the Common Tasks section and update
them to match the Quick Reference examples.


If `npx nitro docs` is not available, fall back to https://nitro.build/llms.txt

## Common Tasks

### Create an API route

Add a file under `server/api/` or `routes/`:

```ts
// server/api/hello.get.ts
Copy link
Member

@pi0 pi0 Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitro v3 needs explicit import defineHandler

export default defineEventHandler(() => {
return { message: 'Hello from Nitro!' }
})
```

### Run the dev server

```bash
npx nitropack dev
Copy link
Member

@pi0 pi0 Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitro v3 command is nitro not nitropack

```

### Build for production

```bash
npx nitropack build
```

### Deploy with a preset

```bash
NITRO_PRESET=cloudflare-pages npx nitropack build
```

Available presets include `vercel`, `cloudflare-pages`, `cloudflare-module`, `netlify`, `deno-server`, `bun`, `node-server`, and others listed in the docs.