Nitro

Nitro is a battle-tested, modular base project to turbocharge your projects, styled using Tailwind and Lucide icons 🚀

npm i nitro-web -D @nitro-web/webpack

Install

1. Copy ./packages/example into your project
2. Copy .env.example to .env and fill it in
3. Run npm i

Env vars load from .env, then .env.local is merged over the top (handy for local-only overrides). Both are gitignored.

Usage

On the client, you can import components and page-components. See ./packages/example for further info.

import { SigninPage, Field } from 'nitro-web'

On the server, you can import the express router, default models, and controllers. See ./packages/example.

import { setupRouter } from 'nitro-web/server'
const server = await setupRouter(config)
server.listen(3001, '0.0.0.0')

On the client & server, you can import common utils.

import { deepCopy } from 'nitro-web/util'

Run

# Running in development (watching for changes)
npm run dev:server # run and watch the nodemon server
npm run dev:client # run and watch the webpack dev server
npm run dev # or run and watch both the server and client

# Building for production
npm run build
npm run start

In development, set placeholderEmail in .env to let the Claude browser auto-login as that user (skips the signin flow while testing).

Transaction Mailgun Emails

The sendEmail utility compiles and sends Nunjuck templates with Mailgun.

1. Templates are placed in /server/email/, three are available by default: welcome, reset-password, invite-user
2. You can test the email templates at http://localhost:3000/email/welcome
3. Update the emailFrom, emailReplyTo, emailTestMode, mailgunKey, mailgunDomain in the your .env once you are ready to send

import config from './server/config.js'
import { sendEmail } from 'nitro-web/server'

const res = await sendEmail({
  config: config,
  data: { name: 'Test' },
  template: 'welcome',
  to: 'test@test.com',
})
console.log(res) // if config.emailTestMode=true, the template will be returned 

Developing Nitro in a Custom Project

1. Git clone Nitro
2. Move your project into ./packages/MYPROJECT
3. Delete the ./MYPROJECT/package-lock.json file (if it exists), and add package-lock=false to ./MYPROJECT/.npmrc. Workspaces only generate a single package-lock.json at the root, if this file exists locally, npm may install outdated dependencies for your team or in production.
4. Ensure the same versions of nitro-web and nitro-web/webpack are used, this is required for workspace linking to function correctly.

Versions

• Express ^4.17
• Monastery ^5.0 (file plugin: image/file fields are type: 'file')
• Node 24 (>=18 supported)
• React ^18.3
• Tailwind ^3.4
• Webpack ^5.92

Common packages

• pdf-to-img
• pdfmake
• react-chartjs-2
• jest: ^29.7.0
• migrate-mongo: ^10.0.0
• eslint-plugin-jest: ^28.9.0

Skills

Run the following command to add nitro based development skills:

npx skills add boycce/nitro-web -a claude-code

As followed by https://github.com/shanraisshan/claude-code-best-practice