An opinionated, production-ready starter kit for modern web applications.
Features • Quick Start • Demo • Contributing
- What's New
- Introduction
- Key Features
- Technology Stack
- Getting Started
- Project Structure
- Typography System
- Utility Library Deep Dive
- Custom Hooks Reference
- Component Showcase
- Configuration Guide
- Contributing
- License
useSoundEffectshook: Lightweight Web Audio API-based sounds for UI feedbackuseSoundhook: Full audio file playback with controls- Sound utilities:
SynthSound,SoundManagerfor centralized audio management
SpotifyModalcomponent: Floating music button with modal player- Supports playlists, albums, tracks, or custom Spotify URLs
- Mute toggle and theme customization
- Scroll Progress Indicator: Gradient progress bar at the top of the page
- Back to Top Button: Floating button with SVG progress ring
- Light/Dark Mode Grid: Optimized bento grid for both themes
- Brand Tech Stack Pills: Colored badges with framework icons
- Performance Optimizations: Lazy loading with
React.lazy()andSuspense
Ourin is not just another Next.js template. It's a meticulously crafted architectural foundation designed to eliminate the repetitive setup phase of every new project. Whether you're building a SaaS product, a marketing site, or an internal tool, Ourin provides a rock-solid starting point that adheres to industry best practices.
We believe developers should spend their time building features, not configuring build tools or copy-pasting utility functions from old projects. That's why Ourin comes pre-loaded with everything you need: a massive library of 185+ utility functions, 20+ custom React hooks, a premium 16-font typography system, example API routes, and a production-ready middleware.
The entire codebase is strictly typed with TypeScript 5, ensuring type safety from the ground up. The styling is powered by Tailwind CSS 4 with its new Oxide engine for blazing-fast builds and zero runtime overhead. And for UI components, we've integrated Shadcn/UI, giving you access to a world-class component library built on accessible Radix UI primitives.
- React Server Components (RSC): By default, all components are server-rendered, minimizing client-side JavaScript and maximizing performance.
- Turbopack: Next.js's new bundler is enabled for near-instant Hot Module Replacement (HMR) during development.
- Zero-Runtime CSS: Tailwind CSS 4's Oxide engine compiles all styles at build time, meaning no CSS-in-JS overhead.
- 16-Font Typography: A carefully curated font stack for every use case—display, body, serif, mono, handwriting, and UI.
- Glassmorphism & Gradients: Pre-built CSS utilities for modern glass effects, text gradients, and shadow glows.
- Dark Mode Built-In: Seamless theme switching using
next-themeswith system preference detection and animated toggle.
- 185+ Utility Functions: Categorized library for strings, arrays, dates, numbers, colors, async, crypto, browser detection, and more.
- 20+ Custom Hooks: Production-ready hooks for debouncing, data fetching, countdown timers, network status, and more.
- Example API Routes: Health check, CRUD users endpoints with pagination and validation.
- Middleware: Pre-configured with security headers, CORS, logging, and auth patterns.
- Strict TypeScript: No
anytypes. Full type safety across the entire project.
- next-intl Integration: Full i18n support out of the box with next-intl.
- Multi-Language Ready: English and Indonesian translations included, easy to add more.
- Language Switcher: Beautiful dropdown component for switching between locales.
- Automatic Locale Detection: Middleware handles locale routing and detection.
- Floating Navbar: A modern, animated navigation bar with scroll-aware visibility.
- Grid Background: Multi-layer background with grid, dots, and diagonal patterns.
- Hooks Showcase: Interactive cards showing all available hooks with diverse fonts.
- Utils Showcase: Category cards with gradient icons for utility functions.
- Copy Command: A sleek terminal-style pill for CLI commands.
| Category | Technology |
|---|---|
| Framework | Next.js 15/16 (App Router, React Server Components) |
| Language | TypeScript 5 (Strict Mode) |
| Styling | Tailwind CSS 4 (Oxide Engine) |
| Components | Shadcn/UI (Radix UI + Tailwind) |
| Animations | Framer Motion |
| Theming | next-themes |
| Icons | Lucide React |
| Fonts | next/font/google |
| Package Manager | pnpm (recommended) |
Before you begin, ensure you have the following installed:
- Node.js: Version 18.x or later (Download)
- pnpm: Recommended package manager (Installation)
- Alternatively, you can use
npmoryarn.
- Alternatively, you can use
The fastest way to get started is using create-next-app with the -e (example) flag:
npx create-next-app -e https://github.com/LuckyArch/ourin-nextjs-starter my-app
cd my-app
pnpm devThis will create a new Next.js project using Ourin as the template in a folder called my-app.
Alternatively, you can clone the repository directly:
-
Clone the repository:
git clone https://github.com/LuckyArch/ourin-nextjs-starter.git cd ourin-nextjs-starter -
Install dependencies:
pnpm install
-
Start the development server:
pnpm dev
-
Open in your browser: Navigate to http://localhost:3000. You should see the Ourin homepage.
The project follows a well-organized, scalable folder structure. Each directory has a clear purpose, making it easy to navigate and extend.
ourin-nextjs-starter/
├── app/ # Next.js App Router
│ ├── globals.css # Global styles, Tailwind config, theme variables (850+ lines)
│ ├── layout.tsx # Root layout: Fonts, ThemeProvider, metadata
│ ├── page.tsx # Homepage: Hero, Features, Code section, Footer
│ ├── privacy/ # Privacy Policy page
│ └── terms/ # Terms of Service page
│
├── components/ # Reusable React components
│ ├── ui/ # Shadcn/UI primitive components
│ │ └── button.tsx # Button component with variants
│ ├── theme-provider.tsx # Wrapper for next-themes
│ └── theme-toggle.tsx # Animated dark/light mode switch
│
├── hooks/ # Custom React hooks
│ ├── index.ts # Central export file for all hooks
│ ├── use-debounce.ts # Debounce a value
│ ├── use-local-storage.ts # Persist state to localStorage
│ ├── use-media-query.ts # Track responsive breakpoints
│ ├── use-on-click-outside.ts # Detect clicks outside an element
│ └── ... (15 hooks total)
│
├── lib/ # Library code and utilities
│ ├── utils.ts # Primary `cn` function for class merging
│ └── utils/ # Categorized utility functions
│ ├── api.ts # Fetch wrapper, error handling
│ ├── array.ts # Array manipulation (chunk, unique, groupBy)
│ ├── color.ts # Color conversion, contrast calculations
│ ├── date.ts # Relative time, duration, date parsing
│ ├── dom.ts # Browser-safe utilities
│ ├── format.ts # Currency, file size, percentage formatting
│ ├── number.ts # Clamping, rounding, random, ordinals
│ ├── object.ts # Deep clone, omit, pick, merge
│ ├── storage.ts # Safe localStorage/sessionStorage wrappers
│ ├── string.ts # Slugify, truncate, capitalize, case converters
│ └── validation.ts # Regex patterns for validation
│
├── config/ # Application configuration
│ └── site.ts # Site name, description, navigation links
│
├── constants/ # Global constants
│ └── index.ts
│
├── types/ # Global TypeScript type definitions
│ └── index.ts
│
├── public/ # Static assets
│ └── logo.png # The Ourin logo
│
├── tailwind.config.ts # Tailwind configuration (optional overrides)
├── tsconfig.json # TypeScript configuration
├── package.json # Project dependencies and scripts
├── CHANGELOG.md # Project version history
└── LICENSE # MIT License
Ourin implements a 6-font typography system to provide maximum flexibility and visual richness. Fonts are loaded efficiently using next/font/google, which automatically optimizes font loading and prevents layout shift.
| CSS Variable | Font Family | Use Case |
|---|---|---|
--font-display |
Outfit | Headings, brand name, hero titles |
--font-sans |
Plus Jakarta Sans | Body text, paragraphs, buttons |
--font-serif |
Playfair Display | Quotes, taglines, elegant accents |
--font-mono |
JetBrains Mono | Code blocks, terminal output, technical data |
--font-hand |
Caveat | Notes, signatures, personal touches |
--font-inter |
Inter | Small labels, metadata, dense UI |
Apply fonts using Tailwind classes:
// Display font for headings
<h1 className="font-display text-5xl font-bold">Welcome to Ourin</h1>
// Serif for elegant accents
<p className="font-serif italic text-lg">"Build better apps, faster."</p>
// Monospace for code
<code className="font-mono text-sm">npm install ourin</code>
// Handwriting for personality
<span className="font-hand text-2xl">— The Team</span>The lib/utils/ directory contains 145+ utility functions categorized by purpose. Here's an in-depth look at each module.
A typed fetch wrapper with timeout, error handling, and response parsing.
import { fetchWithTimeout, handleApiError } from '@/lib/utils/api';
// Fetch with a 5-second timeout
const data = await fetchWithTimeout('/api/users', { timeout: 5000 });Key Functions:
fetchWithTimeout(url, options): Adds timeout to native fetch.handleApiError(error): Standardizes error responses.buildQueryString(params): Converts object to URL query string.
Helpers for common array operations without importing Lodash.
import { chunk, unique, groupBy, shuffle } from '@/lib/utils/array';
chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
unique([1, 1, 2, 3, 3]); // [1, 2, 3]
groupBy(users, 'role'); // { admin: [...], user: [...] }
shuffle([1, 2, 3, 4]); // [3, 1, 4, 2] (randomized)All Functions: chunk, unique, groupBy, shuffle, intersection, difference, flatten, sortBy, take, drop, compact, zip, unzip, range, sample, partition, first, last, findLast, countBy, minBy, maxBy, sumBy.
Format dates in a human-readable way without heavy libraries like Moment.js or date-fns.
import { formatRelativeTime, formatDuration, parseDate } from '@/lib/utils/date';
formatRelativeTime(new Date('2025-12-15')); // "2 days ago"
formatDuration(3661000); // "1h 1m 1s"
parseDate('2025-12-17'); // Date objectAll Functions: formatRelativeTime, formatDuration, parseDate, isValidDate, getStartOfDay, getEndOfDay, addDays, subtractDays, daysBetween, formatDate, isToday, isYesterday, isFuture, isPast.
Format numbers, currency, file sizes, and more.
import { formatCurrency, formatFileSize, formatPercentage, formatPhone } from '@/lib/utils/format';
formatCurrency(1234567.89); // "$1,234,567.89"
formatFileSize(1048576); // "1 MB"
formatPercentage(0.756); // "75.6%"
formatPhone('6281234567890'); // "+62 812-3456-7890"Common string transformations.
import { slugify, truncate, capitalize, camelCase, kebabCase } from '@/lib/utils/string';
slugify('Hello World!'); // "hello-world"
truncate('Long text...', 10); // "Long te..."
capitalize('hello'); // "Hello"
camelCase('foo-bar-baz'); // "fooBarBaz"
kebabCase('fooBarBaz'); // "foo-bar-baz"Regex patterns and validation functions.
import { isEmail, isUrl, isStrongPassword, validateCreditCard } from '@/lib/utils/validation';
isEmail('user@example.com'); // true
isUrl('https://ourin.dev'); // true
isStrongPassword('P@ssw0rd!'); // { valid: true, score: 4 }
validateCreditCard('4111...'); // { valid: true, type: 'visa' }(Similar detail can be provided for color.ts, dom.ts, number.ts, object.ts, and storage.ts if needed.)
The hooks/ directory contains 15 production-ready React hooks. Each hook is fully typed and documented.
Debounces a value. Useful for search inputs to avoid excessive API calls.
const [search, setSearch] = useState('');
const debouncedSearch = useDebounce(search, 500);
useEffect(() => {
// This effect only runs 500ms after the user stops typing
fetchResults(debouncedSearch);
}, [debouncedSearch]);Persists state to localStorage with automatic JSON serialization.
const [user, setUser] = useLocalStorage('user', { name: 'Guest' });Tracks whether a CSS media query matches.
const isMobile = useMediaQuery('(max-width: 768px)');Detects clicks outside a referenced element. Perfect for modals and dropdowns.
const ref = useRef(null);
useOnClickOutside(ref, () => setOpen(false));Tracks the current scroll position of the window.
const { y } = useScrollPosition();
const showBackToTop = y > 500;(Full documentation for all 15 hooks available in the source files.)
A glassmorphism-styled navbar that intelligently hides when scrolling down and reappears when scrolling up. It uses Framer Motion for smooth animations and useScroll from Framer Motion to track scroll position.
Features:
- Scroll-aware visibility (hides on scroll down, shows on scroll up).
- Glassmorphism effect with
backdrop-blurand semi-transparent background. - Fully responsive with mobile-friendly design.
- Integrated theme toggle.
An animated switch between light and dark modes. Uses next-themes for theme management and Framer Motion for the sliding animation of the toggle knob.
A sleek, terminal-style pill component designed for displaying CLI commands with a one-click copy button. The button shows a checkmark animation on successful copy.
An interactive code block that simulates a typing effect. Great for hero sections or feature showcases where you want to draw attention to your code.
Centralize your site's name, description, and URLs.
export const siteConfig = {
name: 'Ourin',
description: 'The ultimate Next.js boilerplate.',
url: 'https://ourin.dev',
ogImage: 'https://ourin.dev/og.png',
links: {
twitter: 'https://twitter.com/ourin',
github: 'https://github.com/LuckyArch/ourin-nextjs-starter',
},
};Customize colors by modifying HSL values in the :root (light mode) and .dark (dark mode) blocks.
:root {
--background: 0 0% 100%;
--foreground: 222.2 84% 4.9%;
--primary: 262.1 83.3% 57.8%; /* Purple */
/* ... */
}
.dark {
--background: 222.2 84% 4.9%;
--foreground: 210 40% 98%;
/* ... */
}Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'feat: add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
We follow Conventional Commits:
feat: A new featurefix: A bug fixdocs: Documentation only changesstyle: Changes that do not affect the meaning of the code (formatting)refactor: A code change that neither fixes a bug nor adds a featureperf: A code change that improves performancetest: Adding missing testschore: Changes to the build process or auxiliary tools
Distributed under the MIT License. See LICENSE for more information.
This means you can use this boilerplate for personal and commercial projects with no attribution required.
Built with ❤️ by Fauzan Adyatma P