{"_id":"@calmsey/frontend-toolkit","name":"@calmsey/frontend-toolkit","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@calmsey/frontend-toolkit","version":"0.0.1","description":"A modern Next.js frontend boilerplate with automatic API code generation, authentication, and UI components","bin":{"create-frontend-toolkit":"bin/create-app.js"},"scripts":{"dev":"next dev --turbopack","build":"next build","start":"next start","lint":"next lint","format":"prettier --write \"src/**/*.{js,jsx,ts,tsx,json,css,md}\"","format:check":"prettier --check \"src/**/*.{js,jsx,ts,tsx,json,css,md}\"","generate:api":"orval --config orval.config.js","prepublishOnly":"node -e \"require('fs').chmodSync('bin/create-app.js', '755')\""},"keywords":["nextjs","next.js","typescript","react-query","tanstack-query","nextauth","orval","shadcn","shadcn-ui","tailwindcss","boilerplate","template","scaffold","starter","frontend","fullstack"],"author":{"name":"Calmsey","email":"wisnuvb@gmail.com","url":"Wisnu Saputro"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/wisnuvb/calmsey-frontend-toolkit.git"},"homepage":"https://github.com/wisnuvb/calmsey-frontend-toolkit#readme","bugs":{"url":"https://github.com/wisnuvb/calmsey-frontend-toolkit/issues"},"dependencies":{"@hookform/resolvers":"^5.2.2","@radix-ui/react-dialog":"^1.1.2","@radix-ui/react-label":"^2.1.1","@radix-ui/react-select":"^2.1.2","@radix-ui/react-slot":"^1.1.1","@radix-ui/react-toast":"^1.2.2","@tanstack/react-query":"^5.90.17","@tanstack/react-query-devtools":"^5.91.2","axios":"^1.13.2","class-variance-authority":"^0.7.1","clsx":"^2.1.1","lucide-react":"^0.562.0","next":"^16.1.1","next-auth":"^4.24.13","react":"^19.2.3","react-dom":"^19.2.3","react-hook-form":"^7.71.1","sonner":"^1.7.0","tailwind-merge":"^3.4.0","zod":"^4.3.5"},"devDependencies":{"@orval/core":"^7.18.0","@orval/zod":"^7.18.0","@types/node":"^25.0.8","@types/react":"^19.2.8","@types/react-dom":"^19.2.3","autoprefixer":"^10.4.23","eslint":"^9.39.2","eslint-config-next":"^16.1.1","eslint-config-prettier":"^10.1.8","orval":"^7.18.0","postcss":"^8.5.6","prettier":"^3.7.4","tailwindcss":"^3.4.19","tailwindcss-animate":"^1.0.7","typescript":"^5.9.3"},"_id":"@calmsey/frontend-toolkit@0.0.1","gitHead":"ab272f6270583a7d313e6bfa6cfc3f6187d4c44c","_nodeVersion":"20.15.1","_npmVersion":"10.9.0","dist":{"integrity":"sha512-u33FSPoTh4qysBazaF7FS7laJousv/NALVX3xzRimagoMlCaoos6c4FqP8wp72TACAPTZ5I7qNPZQNrJ2SWkEw==","shasum":"db0bff1c44ed8253742d31c80cd549b77cdd2f65","tarball":"https://registry.npmjs.org/@calmsey/frontend-toolkit/-/frontend-toolkit-0.0.1.tgz","fileCount":68,"unpackedSize":152175,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDJpKky8zFwXyGOez2oyBF/Z6iJWrmElXl3D6cbnt8QTAiEA7eNqCQGeLQGr0zEyPubmIMfPNdS5F7/FJ5CSseC7OXo="}]},"_npmUser":{"name":"wisnuvb","email":"wisnuvb@gmail.com"},"directories":{},"maintainers":[{"name":"wisnuvb","email":"wisnuvb@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/frontend-toolkit_0.0.1_1768390761272_0.7991616061789335"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-14T11:39:21.187Z","0.0.1":"2026-01-14T11:39:21.413Z","modified":"2026-01-14T11:39:21.960Z"},"maintainers":[{"name":"wisnuvb","email":"wisnuvb@gmail.com"}],"description":"A modern Next.js frontend boilerplate with automatic API code generation, authentication, and UI components","homepage":"https://github.com/wisnuvb/calmsey-frontend-toolkit#readme","keywords":["nextjs","next.js","typescript","react-query","tanstack-query","nextauth","orval","shadcn","shadcn-ui","tailwindcss","boilerplate","template","scaffold","starter","frontend","fullstack"],"repository":{"type":"git","url":"git+https://github.com/wisnuvb/calmsey-frontend-toolkit.git"},"author":{"name":"Calmsey","email":"wisnuvb@gmail.com","url":"Wisnu Saputro"},"bugs":{"url":"https://github.com/wisnuvb/calmsey-frontend-toolkit/issues"},"license":"MIT","readme":"# Frontend Toolset\n\nA modern Next.js frontend boilerplate with automatic API code generation, authentication, and UI components.\n\n## 🎯 Use Cases\n\nThis project supports **two scenarios** for API usage:\n\n1. **Fullstack** - Using Next.js API Routes (integrated backend)\n2. **External API** - Consuming API from a separate backend (microservices, REST API, etc.)\n\nSee [API_ARCHITECTURE.md](./API_ARCHITECTURE.md) for a complete guide.\n\n## 🚀 Features\n\n- **Next.js 15** - App Router with Server Components\n- **TypeScript** - Type-safe development\n- **TanStack Query (React Query)** - Powerful data fetching and caching\n- **NextAuth.js** - Authentication with JWT strategy\n- **Orval** - Automatic API client generation from OpenAPI/Swagger\n- **Shadcn UI** - Beautiful and accessible UI components\n- **Tailwind CSS** - Utility-first CSS framework\n- **Axios** - HTTP client with interceptors for auth\n\n## 📁 Project Structure\n\n```\nfrontend-toolset/\n├── public/                    # Static assets\n├── src/\n│   ├── app/                   # Next.js App Router\n│   │   ├── (auth)/           # Auth route group (login, register)\n│   │   ├── (dashboard)/      # Dashboard route group (protected)\n│   │   ├── api/              # API routes\n│   │   │   └── auth/         # NextAuth endpoints\n│   │   ├── layout.tsx        # Root layout with providers\n│   │   ├── page.tsx          # Homepage\n│   │   └── globals.css       # Global styles\n│   │\n│   ├── components/           # UI Components\n│   │   ├── ui/              # Shadcn UI components\n│   │   ├── shared/          # Shared components (Navbar, Footer)\n│   │   └── forms/           # Form components\n│   │\n│   ├── hooks/               # Custom React hooks\n│   │\n│   ├── lib/                 # Library configurations\n│   │   ├── auth.ts         # NextAuth configuration\n│   │   ├── axios.ts        # Axios instance with interceptors\n│   │   ├── query-client.ts # React Query configuration\n│   │   └── utils.ts        # Utility functions (cn merger)\n│   │\n│   ├── services/            # API Integration Layer\n│   │   ├── api/            # Auto-generated by Orval\n│   │   │   ├── model/      # TypeScript interfaces from OpenAPI\n│   │   │   └── endpoints/  # Generated React Query hooks\n│   │   └── custom/         # Manual API services\n│   │\n│   ├── schemas/            # Zod validation schemas\n│   ├── store/              # State management (Zustand/Jotai)\n│   ├── types/              # Global TypeScript types\n│   └── providers/          # React context providers\n│\n├── orval.config.js         # Orval configuration\n├── tailwind.config.ts      # Tailwind configuration\n├── components.json         # Shadcn UI configuration\n├── next.config.mjs         # Next.js configuration\n└── tsconfig.json          # TypeScript configuration\n```\n\n## 🛠️ Quick Start\n\n### Option 1: Install via npx (Recommended)\n\nCreate a new project instantly:\n\n```bash\nnpx @wisnuvb/frontend-toolkit my-app\ncd my-app\nnpm run dev\n```\n\n### Option 2: Clone from Repository\n\n1. Clone the repository:\n\n```bash\ngit clone <repository-url>\ncd frontend-toolset\n```\n\n2. Install dependencies:\n\n```bash\nnpm install\n```\n\n3. Create environment file:\n\n```bash\n# Copy ENV_TEMPLATE.md content to .env.local\n# Or generate NEXTAUTH_SECRET:\nopenssl rand -base64 32\n```\n\n4. Update environment variables in `.env.local`:\n\n```env\nNEXTAUTH_URL=http://localhost:3000\nNEXTAUTH_SECRET=your-generated-secret-key\nNEXT_PUBLIC_API_URL=http://localhost:3000/api\n```\n\n5. Configure Orval:\n   - Update `orval.config.js` with your OpenAPI/Swagger spec URL\n   - Run API generation:\n\n```bash\nnpm run generate:api\n```\n\n6. Start development server:\n\n```bash\nnpm run dev\n```\n\nVisit [http://localhost:3000](http://localhost:3000)\n\n### Prerequisites\n\n- Node.js 18+\n- npm/yarn/pnpm\n\n## 📝 Usage\n\n### API Code Generation with Orval\n\nOrval automatically generates TypeScript types and React Query hooks from your OpenAPI spec.\n\n1. **Configure OpenAPI source** in `orval.config.js`:\n\n```javascript\ninput: {\n  target: 'https://api.example.com/swagger.json', // Your API spec\n}\n```\n\n2. **Generate API client**:\n\n```bash\nnpm run generate:api\n```\n\n3. **Use generated hooks**:\n\n```typescript\nimport { useGetUsers } from '@/services/api/endpoints/users';\n\nfunction UsersList() {\n  const { data, isLoading, error } = useGetUsers();\n\n  if (isLoading) return <div>Loading...</div>;\n  if (error) return <div>Error loading users</div>;\n\n  return (\n    <ul>\n      {data?.map(user => (\n        <li key={user.id}>{user.name}</li>\n      ))}\n    </ul>\n  );\n}\n```\n\n### Authentication\n\nThe project uses NextAuth.js with JWT strategy.\n\n**Login example**:\n\n```typescript\nimport { signIn } from 'next-auth/react';\n\nconst handleLogin = async () => {\n  await signIn('credentials', {\n    email: 'user@example.com',\n    password: 'password',\n  });\n};\n```\n\n**Protected routes**:\n\n```typescript\n'use client';\nimport { useSession } from 'next-auth/react';\nimport { redirect } from 'next/navigation';\n\nexport default function ProtectedPage() {\n  const { data: session, status } = useSession();\n\n  if (status === 'unauthenticated') {\n    redirect('/login');\n  }\n\n  return <div>Protected content</div>;\n}\n```\n\n### Using Shadcn UI Components\n\nInstall components as needed:\n\n```bash\nnpx shadcn@latest add button\nnpx shadcn@latest add card\nnpx shadcn@latest add input\n```\n\nUse in your components:\n\n```typescript\nimport { Button } from '@/components/ui/button';\n\nfunction MyComponent() {\n  return <Button>Click me</Button>;\n}\n```\n\n### Forms with React Hook Form + Zod\n\n```typescript\nimport { useForm } from 'react-hook-form';\nimport { zodResolver } from '@hookform/resolvers/zod';\nimport { z } from 'zod';\n\nconst schema = z.object({\n  email: z.string().email(),\n  password: z.string().min(8),\n});\n\ntype FormData = z.infer<typeof schema>;\n\nfunction LoginForm() {\n  const { register, handleSubmit, formState: { errors } } = useForm<FormData>({\n    resolver: zodResolver(schema),\n  });\n\n  const onSubmit = (data: FormData) => {\n    console.log(data);\n  };\n\n  return (\n    <form onSubmit={handleSubmit(onSubmit)}>\n      <input {...register('email')} />\n      {errors.email && <span>{errors.email.message}</span>}\n\n      <input type=\"password\" {...register('password')} />\n      {errors.password && <span>{errors.password.message}</span>}\n\n      <button type=\"submit\">Login</button>\n    </form>\n  );\n}\n```\n\n## 🔧 Configuration\n\n### Axios Interceptors\n\nThe Axios instance in `src/lib/axios.ts` automatically:\n\n- Adds Bearer token from NextAuth session\n- Handles 401 Unauthorized responses\n- Can be extended for other interceptors\n\n### React Query Settings\n\nConfigured in `src/lib/query-client.ts`:\n\n- Default stale time: 1 minute\n- Retry failed requests: 1 time\n- No refetch on window focus\n\n### API Base URL\n\nSet in environment variables:\n\n```env\nNEXT_PUBLIC_API_URL=https://api.example.com\n```\n\n## 📜 Available Scripts\n\n- `npm run dev` - Start development server with Turbopack\n- `npm run build` - Build for production\n- `npm run start` - Start production server\n- `npm run lint` - Run ESLint\n- `npm run generate:api` - Generate API client from OpenAPI spec\n\n## 🎨 Customization\n\n### Tailwind Theme\n\nCustomize colors and styling in `tailwind.config.ts`.\n\n### Shadcn UI Theme\n\nModify CSS variables in `src/app/globals.css` to change theme colors.\n\n### Adding New API Endpoints (Manual)\n\nFor endpoints not covered by Orval:\n\n1. Create a service in `src/services/custom/`:\n\n```typescript\n// src/services/custom/my-service.ts\nimport { axiosInstance } from '@/lib/axios';\n\nexport const myCustomApi = {\n  getData: async () => {\n    const { data } = await axiosInstance.get('/custom-endpoint');\n    return data;\n  },\n};\n```\n\n2. Create a React Query hook:\n\n```typescript\n// src/hooks/useCustomData.ts\nimport { useQuery } from '@tanstack/react-query';\nimport { myCustomApi } from '@/services/custom/my-service';\n\nexport function useCustomData() {\n  return useQuery({\n    queryKey: ['customData'],\n    queryFn: myCustomApi.getData,\n  });\n}\n```\n\n## 🚀 Deployment\n\n### Vercel (Recommended)\n\n1. Push code to GitHub\n2. Import project in Vercel\n3. Configure environment variables\n4. Deploy\n\n### Docker\n\n```bash\ndocker build -t frontend-toolset .\ndocker run -p 3000:3000 frontend-toolset\n```\n\n## 📚 Resources\n\n- [Next.js Documentation](https://nextjs.org/docs)\n- [TanStack Query](https://tanstack.com/query/latest)\n- [NextAuth.js](https://next-auth.js.org/)\n- [Orval](https://orval.dev/)\n- [Shadcn UI](https://ui.shadcn.com/)\n- [Tailwind CSS](https://tailwindcss.com/)\n\n## 📄 License\n\nMIT\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n","readmeFilename":"README.md","_rev":"1-e76e564f6cd8fb8267a2c0bb44617556"}