Open-source Next.js starter template with pre-loaded optimizations and AI-friendly development tools
A production-ready Next.js template designed for modern development workflows with AI assistance. It includes optional productivity features that eliminate common friction points in Next.js development.
- ✅ Next.js with App Router
- ✅ TypeScript for type safety
- ✅ Tailwind CSS for styling
- ✅ ESLint for code quality
- ✅ Turbopack for faster development
- 🎯 Agent Verify - Health check utility (optional)
- 🔫 Autokill - Automatic process management (optional)
- 🎲 Port Randomizer - Smart port selection (optional)
# Clone the repository
git clone https://github.com/Next-AI-Labs-Inc/agentic-next-starter.git my-project
cd my-project
# Install dependencies
npm install
# Run configuration (first time only)
npm run configure
# Start development
npm run devOn first run, you'll be guided through an interactive setup:
npm run configureThis configures optional agentic features:
- Agent Verify - Health checking for your app
- Autokill - Automatically kill processes on your port
- Port Randomizer - Find available ports automatically
All features are optional and can be enabled/disabled anytime.
Problem Solved: Manual health checking is tedious and error-prone.
Solution: Automated health verification with detailed reporting.
npm run agent-verifyFeatures:
- Checks if your app is responding
- Provides detailed error messages
- Suggests fixes for common issues
- Logs results to
.agent-health-check.log
Problem Solved: Multiple terminal windows make it hard to find which one is running your app.
Solution: Automatically kills processes on your port before starting.
npm run dev:autokillFeatures:
- Finds all processes on your port
- Kills them automatically
- Starts your app immediately
- Handles multiple processes
Problem Solved: Port conflicts waste time during development.
Solution: Automatically finds and uses available ports.
npm run dev:randomFeatures:
- Tries preferred port first
- Falls back to last used port
- Finds random available port
- Persists port for consistency
npm run dev# Health check before starting
npm run agent-verify && npm run dev
# Auto-kill and start
npm run dev:autokill
# Use random available port
npm run dev:random{
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "next lint",
"configure": "node scripts/configure.js",
"agent-verify": "Uses @agentic-next/verify",
"dev:autokill": "Uses @agentic-next/autokill",
"dev:random": "Uses @agentic-next/port-randomizer"
}Configuration is stored in .agentic-config.json:
{
"features": {
"agentVerify": true,
"autokill": true,
"portRandomizer": false
},
"settings": {
"port": 3000,
"portRange": {
"min": 3000,
"max": 9999
}
}
}Reconfigure anytime:
npm run configure -- --forceAll agentic features are separate npm modules:
| Module | Purpose | Status |
|---|---|---|
| @agentic-next/verify | Health checking | ✅ Ready |
| @agentic-next/autokill | Process management | ✅ Ready |
| @agentic-next/port-randomizer | Port selection | ✅ Ready |
Each module can be used independently in any Node.js project.
This starter is optimized for AI-assisted development. See AGENTS.md for:
- AI agent protocols
- Module development guidelines
- Configuration handling rules
- Publishing requirements
Key Rules:
- All features are optional
- Respect user configuration
- Modules work independently
- Never publish without consent
agentic-next-starter/
├── app/ # Next.js app directory
├── packages/ # Agentic feature modules
│ ├── verify/ # @agentic-next/verify
│ ├── autokill/ # @agentic-next/autokill
│ └── port-randomizer/ # @agentic-next/port-randomizer
├── scripts/ # Build and setup scripts
│ └── configure.js # First-run configuration
├── public/ # Static assets
├── .agentic-config.json # Feature configuration
├── AGENTS.md # AI agent rules
└── README.md # This file
# 1. Start development
npm run dev
# 2. Make changes
# 3. Build for production
npm run build
# 4. Test production build
npm start# 1. Verify app health
npm run agent-verify
# 2. Start with autokill (no port conflicts)
npm run dev:autokill
# 3. Or use random port
npm run dev:random
# 4. Make changes and verify again
npm run agent-verifyRun multiple Next.js projects simultaneously:
# Project A
cd project-a && npm run dev:random
# → Started on http://localhost:3542
# Project B
cd project-b && npm run dev:random
# → Started on http://localhost:3789# In your CI pipeline
npm run agent-verify || exit 1
npm run build// Use port randomizer to avoid conflicts
const PortRandomizer = require('@agentic-next/port-randomizer');
const { port } = await new PortRandomizer().getPort();
// Use in docker-compose.yml- Create module in
packages/your-feature/ - Add to configuration system
- Update README
- See AGENTS.md for guidelines
Each module is independent:
cd packages/verify
# Make changes
npm link
# Test in your projectvercel deploynpm run build
npm startNo! All features are optional. Enable only what you need.
Yes! Each module works independently in any Node.js project.
Run npm run configure -- --force and toggle features.
Not yet. They will be published after thorough testing.
Yes! See AGENTS.md for contribution guidelines.
- Agent Verify module
- Autokill module
- Port Randomizer module
- Configuration system
- Documentation
- Publish modules to npm
- Add more agentic features
- VS Code extension
- CLI tool
- AGENTS.md - AI agent protocols
- Module READMEs - Individual feature docs
MIT License - see LICENSE for details
Created by Next AI Labs
Built on Next.js by Vercel
Happy Building! 🚀
Made with ❤️ for developers who build with AI