Revamp README.md to reflect project rebranding as "High Performance Structures" with comprehensive tech stack, features, and development workflows. Enhance installation instructions and deployment processes for Cloudflare Workers.
This commit is contained in:
parent
0a33fd8530
commit
e1b80037d9
374
README.md
374
README.md
@ -1,47 +1,363 @@
|
|||||||
# OpenNext Starter
|
# High Performance Structures Website
|
||||||
|
|
||||||
This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
|
A modern, high-performance website for High Performance Structures - a Colorado-based company specializing in Insulating Concrete Form (ICF) construction services. Built with Next.js 16 and deployed to Cloudflare Workers for global edge distribution.
|
||||||
|
|
||||||
## Getting Started
|
## 🚀 Tech Stack
|
||||||
|
|
||||||
Read the documentation at https://opennext.js.org/cloudflare.
|
- **Framework:** [Next.js 16](https://nextjs.org/) with App Router
|
||||||
|
- **UI Library:** [React 19](https://react.dev/)
|
||||||
|
- **Language:** [TypeScript](https://www.typescriptlang.org/)
|
||||||
|
- **Styling:** [Tailwind CSS v4](https://tailwindcss.com/) with CSS variables
|
||||||
|
- **Components:** [shadcn/ui](https://ui.shadcn.com/) (Radix UI primitives)
|
||||||
|
- **Deployment:** [Cloudflare Workers](https://developers.cloudflare.com/workers/)
|
||||||
|
- **Bridge:** [OpenNext Cloudflare](https://opennext.js.org/cloudflare)
|
||||||
|
- **Icons:** [Lucide React](https://lucide.dev/)
|
||||||
|
- **Forms:** [React Hook Form](https://react-hook-form.com/) + [Zod](https://zod.dev/)
|
||||||
|
- **Analytics:** [Vercel Web Analytics](https://vercel.com/analytics)
|
||||||
|
|
||||||
## Develop
|
## ✨ Features
|
||||||
|
|
||||||
Run the Next.js development server:
|
- **Responsive Design** - Mobile-first approach with optimized layouts for all screen sizes
|
||||||
|
- **Modern UI** - Clean, professional interface built with shadcn/ui components
|
||||||
|
- **Server-Side Rendering** - SSR/SSG capabilities for optimal performance and SEO
|
||||||
|
- **Edge Deployment** - Global distribution via Cloudflare's edge network
|
||||||
|
- **Blog System** - Dynamic blog post pages with markdown support
|
||||||
|
- **Contact Forms** - Validated contact forms with React Hook Form and Zod
|
||||||
|
- **Service Showcases** - Dedicated pages for ICF services, training, and resources
|
||||||
|
- **Performance Optimized** - Fast page loads with optimized images and static assets
|
||||||
|
|
||||||
|
## 📋 Prerequisites
|
||||||
|
|
||||||
|
- **Node.js** 18.x or higher
|
||||||
|
- **pnpm** (package manager) - Install with `npm install -g pnpm`
|
||||||
|
- **Cloudflare Account** (for deployment)
|
||||||
|
|
||||||
|
## 🛠️ Getting Started
|
||||||
|
|
||||||
|
### Installation
|
||||||
|
|
||||||
|
1. Clone the repository:
|
||||||
```bash
|
```bash
|
||||||
npm run dev
|
git clone <repository-url>
|
||||||
# or similar package manager command
|
cd high-performance-structures
|
||||||
```
|
```
|
||||||
|
|
||||||
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
|
2. Install dependencies:
|
||||||
|
|
||||||
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
|
|
||||||
|
|
||||||
## Preview
|
|
||||||
|
|
||||||
Preview the application locally on the Cloudflare runtime:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm run preview
|
pnpm install
|
||||||
# or similar package manager command
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Deploy
|
3. Start the development server:
|
||||||
|
|
||||||
Deploy the application to Cloudflare:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm run deploy
|
pnpm dev
|
||||||
# or similar package manager command
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Learn More
|
4. Open [http://localhost:3000](http://localhost:3000) in your browser.
|
||||||
|
|
||||||
To learn more about Next.js, take a look at the following resources:
|
The page will automatically reload when you make changes to the code.
|
||||||
|
|
||||||
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
|
## 📜 Available Scripts
|
||||||
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
|
|
||||||
|
|
||||||
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
|
### Development
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pnpm dev # Start Next.js dev server (http://localhost:3000)
|
||||||
|
pnpm lint # Run ESLint code quality checks
|
||||||
|
```
|
||||||
|
|
||||||
|
### Build & Deployment
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pnpm build # Create production build (.next/ and .open-next/ outputs)
|
||||||
|
pnpm start # Start production server locally
|
||||||
|
pnpm preview # Test on Cloudflare Workers runtime locally
|
||||||
|
pnpm deploy # Deploy to Cloudflare Workers (requires authentication)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Component Management
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx shadcn-ui@latest add [component-name] # Add shadcn/ui component
|
||||||
|
```
|
||||||
|
|
||||||
|
## 📁 Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
high-performance-structures/
|
||||||
|
├── app/ # Next.js App Router pages
|
||||||
|
│ ├── page.tsx # Home page
|
||||||
|
│ ├── layout.tsx # Root layout with metadata
|
||||||
|
│ ├── globals.css # Global styles and Tailwind config
|
||||||
|
│ ├── blog/ # Blog pages
|
||||||
|
│ │ ├── page.tsx # Blog listing
|
||||||
|
│ │ └── [slug]/ # Dynamic blog post pages
|
||||||
|
│ ├── services/ # Services page
|
||||||
|
│ ├── contact/ # Contact page
|
||||||
|
│ └── resources/ # Resources page
|
||||||
|
├── components/ # React components
|
||||||
|
│ ├── ui/ # shadcn/ui components (30+ components)
|
||||||
|
│ ├── site-header.tsx # Site header with navigation
|
||||||
|
│ ├── site-footer.tsx # Site footer
|
||||||
|
│ └── hps-logo.tsx # Brand logo component
|
||||||
|
├── lib/ # Utilities
|
||||||
|
│ └── utils.ts # cn() function for merging Tailwind classes
|
||||||
|
├── hooks/ # Custom React hooks
|
||||||
|
│ ├── use-toast.ts # Toast notifications
|
||||||
|
│ └── use-mobile.ts # Mobile detection
|
||||||
|
├── public/ # Static assets
|
||||||
|
│ ├── images/ # Image assets
|
||||||
|
│ ├── logos/ # Logo files
|
||||||
|
│ └── _headers # Cloudflare caching rules
|
||||||
|
├── next.config.ts # Next.js configuration
|
||||||
|
├── wrangler.jsonc # Cloudflare Workers configuration
|
||||||
|
├── open-next.config.ts # OpenNext bridge configuration
|
||||||
|
├── tsconfig.json # TypeScript configuration
|
||||||
|
└── package.json # Dependencies and scripts
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🏗️ Architecture
|
||||||
|
|
||||||
|
### High-Level Stack
|
||||||
|
|
||||||
|
```
|
||||||
|
React 19 Components
|
||||||
|
↓
|
||||||
|
Next.js 16 App Router (SSR/SSG)
|
||||||
|
↓
|
||||||
|
Cloudflare Workers (via OpenNext bridge)
|
||||||
|
↓
|
||||||
|
Cloudflare Edge Network (global distribution)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Build Outputs
|
||||||
|
|
||||||
|
- **`.next/`** - Standard Next.js build output
|
||||||
|
- **`.open-next/`** - OpenNext bridge output for Cloudflare
|
||||||
|
- `worker.js` - Cloudflare Worker entry point
|
||||||
|
- `assets/` - Static files for edge serving
|
||||||
|
|
||||||
|
## ⚙️ Configuration
|
||||||
|
|
||||||
|
### TypeScript Path Aliases
|
||||||
|
|
||||||
|
The project uses path aliases for cleaner imports:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"paths": {
|
||||||
|
"@/*": ["./*"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Import pattern:** `import { Component } from "@/components/Component"`
|
||||||
|
|
||||||
|
### Tailwind CSS v4
|
||||||
|
|
||||||
|
The project uses **Tailwind CSS v4** with CSS-only configuration in `app/globals.css`:
|
||||||
|
|
||||||
|
```css
|
||||||
|
@import "tailwindcss";
|
||||||
|
|
||||||
|
:root {
|
||||||
|
--primary-blue: #0066bf;
|
||||||
|
--deep-navy: #0f172a;
|
||||||
|
--cyan-accent: #8cc63f;
|
||||||
|
/* ... more variables ... */
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Brand Colors:**
|
||||||
|
- Deep Navy: `#0f172a` - Primary background
|
||||||
|
- Primary Blue: `#0066bf` - Action elements
|
||||||
|
- Cyan/Lime Accent: `#8cc63f` - Brand highlight
|
||||||
|
|
||||||
|
Dark mode is supported via `next-themes` package.
|
||||||
|
|
||||||
|
### Component Library (shadcn/ui)
|
||||||
|
|
||||||
|
All UI components use **shadcn/ui** (Radix UI primitives + Tailwind):
|
||||||
|
- Location: `components/ui/`
|
||||||
|
- Style: New York (modern, clean)
|
||||||
|
- Icons: Lucide React
|
||||||
|
- Installation: `npx shadcn-ui@latest add [component]`
|
||||||
|
- Configuration: `components.json`
|
||||||
|
|
||||||
|
## 🔧 Development Workflows
|
||||||
|
|
||||||
|
### Adding a New Page
|
||||||
|
|
||||||
|
1. Create directory under `app/` (e.g., `app/new-page/`)
|
||||||
|
2. Add `page.tsx` file with default export component:
|
||||||
|
```typescript
|
||||||
|
export default function NewPage() {
|
||||||
|
return <div>New Page Content</div>
|
||||||
|
}
|
||||||
|
```
|
||||||
|
3. Optionally create `layout.tsx` for page-specific layout
|
||||||
|
4. Import `SiteHeader` and `SiteFooter` for consistent layout
|
||||||
|
|
||||||
|
### Adding UI Components
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx shadcn-ui@latest add button
|
||||||
|
npx shadcn-ui@latest add card
|
||||||
|
npx shadcn-ui@latest add form
|
||||||
|
```
|
||||||
|
|
||||||
|
All components are composable and styled with Tailwind.
|
||||||
|
|
||||||
|
### Creating Forms
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { useForm } from "react-hook-form"
|
||||||
|
import { zodResolver } from "@hookform/resolvers/zod"
|
||||||
|
import { z } from "zod"
|
||||||
|
|
||||||
|
const schema = z.object({
|
||||||
|
email: z.string().email("Invalid email"),
|
||||||
|
message: z.string().min(10),
|
||||||
|
})
|
||||||
|
|
||||||
|
export default function MyForm() {
|
||||||
|
const form = useForm({
|
||||||
|
resolver: zodResolver(schema),
|
||||||
|
})
|
||||||
|
// form.register(), form.handleSubmit(), etc.
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Dark Mode Implementation
|
||||||
|
|
||||||
|
Uses `next-themes`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { useTheme } from "next-themes"
|
||||||
|
|
||||||
|
const { theme, setTheme } = useTheme()
|
||||||
|
```
|
||||||
|
|
||||||
|
CSS dark mode via `prefers-color-scheme` media query + `.dark` class support.
|
||||||
|
|
||||||
|
## 🚢 Deployment
|
||||||
|
|
||||||
|
### Cloudflare Workers Configuration
|
||||||
|
|
||||||
|
**Wrangler Setup** (`wrangler.jsonc`):
|
||||||
|
- Worker entry: `.open-next/worker.js`
|
||||||
|
- Compatibility date: `2025-03-01`
|
||||||
|
- Node.js compatibility enabled: `nodejs_compat` flag
|
||||||
|
- Static assets binding: `ASSETS` → `.open-next/assets`
|
||||||
|
- Observability: Enabled
|
||||||
|
|
||||||
|
### Deployment Process
|
||||||
|
|
||||||
|
**Important:** Follow these steps in order:
|
||||||
|
|
||||||
|
1. **Build for Cloudflare:**
|
||||||
|
```bash
|
||||||
|
npx @opennextjs/cloudflare build
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Deploy to Cloudflare:**
|
||||||
|
```bash
|
||||||
|
npx wrangler deploy
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note:** Do NOT skip the build step. Wrangler deploys without this step will push stale assets.
|
||||||
|
|
||||||
|
### Caching Strategy
|
||||||
|
|
||||||
|
**Static assets** (in `public/_headers`):
|
||||||
|
```
|
||||||
|
/_next/static/*
|
||||||
|
Cache-Control: public,max-age=31536000,immutable
|
||||||
|
```
|
||||||
|
|
||||||
|
- Cached for 1 year at edge
|
||||||
|
- Content hash in filename ensures cache busting
|
||||||
|
|
||||||
|
### Account Management
|
||||||
|
|
||||||
|
Cloudflare account is stored in local Wrangler config (`~/.wrangler/config.json`). To switch accounts:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
wrangler logout
|
||||||
|
wrangler login
|
||||||
|
```
|
||||||
|
|
||||||
|
### Local Preview
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pnpm preview
|
||||||
|
```
|
||||||
|
|
||||||
|
Simulates Cloudflare Workers runtime locally using Wrangler.
|
||||||
|
|
||||||
|
## 🔐 Environment Variables
|
||||||
|
|
||||||
|
### Development
|
||||||
|
|
||||||
|
- **File:** `.dev.vars` (Git ignored)
|
||||||
|
- **Template:** `.dev.vars.example`
|
||||||
|
- **Content:** Currently just `NEXTJS_ENV=development`
|
||||||
|
|
||||||
|
Used by Wrangler for local development. Extend as needed for API keys, secrets, etc.
|
||||||
|
|
||||||
|
### Production
|
||||||
|
|
||||||
|
Set environment variables in Cloudflare Dashboard or via Wrangler:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
wrangler secret put MY_SECRET
|
||||||
|
```
|
||||||
|
|
||||||
|
## 📚 Additional Resources
|
||||||
|
|
||||||
|
### Documentation
|
||||||
|
|
||||||
|
- [Next.js Documentation](https://nextjs.org/docs)
|
||||||
|
- [OpenNext Cloudflare](https://opennext.js.org/cloudflare)
|
||||||
|
- [Tailwind CSS v4](https://tailwindcss.com/docs)
|
||||||
|
- [shadcn/ui](https://ui.shadcn.com/)
|
||||||
|
- [Cloudflare Workers](https://developers.cloudflare.com/workers/)
|
||||||
|
- [React Hook Form](https://react-hook-form.com/)
|
||||||
|
- [Zod](https://zod.dev/)
|
||||||
|
|
||||||
|
### Related Tools
|
||||||
|
|
||||||
|
- [Radix UI](https://www.radix-ui.com/) - Unstyled, accessible component primitives
|
||||||
|
- [Lucide Icons](https://lucide.dev/) - Beautiful icon library
|
||||||
|
- [Vercel Analytics](https://vercel.com/analytics) - Web analytics
|
||||||
|
|
||||||
|
## 🐛 Troubleshooting
|
||||||
|
|
||||||
|
### Module not found errors for `@/lib/utils` or components
|
||||||
|
|
||||||
|
Ensure files exist in project root at correct paths and `tsconfig.json` path alias points to `"./*"`.
|
||||||
|
|
||||||
|
### OpenNext Cloudflare for Dev
|
||||||
|
|
||||||
|
The `initOpenNextCloudflareForDev()` call in `next.config.ts` enables `getCloudflareContext()` usage in `next dev` mode.
|
||||||
|
|
||||||
|
### React 19 Compatibility
|
||||||
|
|
||||||
|
- `vaul@^1.0.0` required (not 0.9.x which only supports React 18)
|
||||||
|
- All shadcn/ui components tested with React 19
|
||||||
|
|
||||||
|
### Build Errors
|
||||||
|
|
||||||
|
- **ESLint config errors during build:** They're informational—build still succeeds, but you should address them separately.
|
||||||
|
- **Viewport metadata warning:** Move viewport values from metadata to generateViewport per Next.js docs.
|
||||||
|
|
||||||
|
## 📝 License
|
||||||
|
|
||||||
|
Private project - All rights reserved.
|
||||||
|
|
||||||
|
## 👥 Contact
|
||||||
|
|
||||||
|
For questions about this project, please contact the development team.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Built with ❤️ using Next.js and Cloudflare Workers
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user