shortcut-next 0.1.0

package/README.md

@@ -0,0 +1,25 @@
+# Quickstart Next ⚡
+
+> Scaffold modern **Next.js 15+ projects** in seconds — with **MUI**, **React Hook Form**, and **TanStack Query** built-in.  
+> Optionally add **Tailwind CSS v4** with a single command.
+
+---
+
+## 🚀 Features
+
+- **Next.js 15 (App Router)** — modern project structure, ready to go.
+- **MUI (Material UI)** — theming, components, dark mode ready.
+- **React Hook Form** — forms made simple, integrated with MUI inputs.
+- **TanStack Query (React Query)** — powerful data fetching and caching.
+- **Tailwind CSS v4** (optional) — utility-first styling, zero config.
+- **TypeScript by default** — strict mode enabled.
+- **One CLI** — choose your preset: **Base** (MUI stack) or **Tailwind v4**.
+
+---
+
+## 📦 Installation
+
+You don’t need to install globally. Use `npx`:
+
+```bash
+npx @hadi87s/quickstart-next@latest

package/bin/quickstart-next.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import('../src/run.mjs').catch(e => {
+  console.error(e);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "shortcut-next",
+  "version": "0.1.0",
+  "description": "Scaffold Next.js apps with MUI base or Tailwind v4 preset.",
+  "main": "index.js",
+  "bin": {
+    "shortcut-next": "bin/quickstart-next.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hadi87s/quickstart-next.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hadi87s/quickstart-next/issues"
+  },
+  "homepage": "https://github.com/hadi87s/quickstart-next#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "cac": "^6.7.14",
+    "execa": "^9.6.0",
+    "fs-extra": "^11.3.1",
+    "kolorist": "^1.8.0",
+    "ora": "^8.2.0"
+  }
+}

package/src/run.mjs

@@ -0,0 +1,130 @@
+import { cac } from 'cac';
+import * as p from '@clack/prompts';
+import { cyan, green, yellow } from 'kolorist';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs-extra';
+import { execa } from 'execa';
+import ora from 'ora';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = path.join(__dirname, '..', 'templates', 'base'); // single base template
+
+async function addTailwindV4(dest) {
+  // 1) Merge Tailwind v4 devDeps (remove any old ones if present)
+  const pkgPath = path.join(dest, 'package.json');
+  const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
+
+  // Ensure devDependencies object exists
+  pkg.devDependencies = pkg.devDependencies || {};
+  // Remove v3-era keys if they exist
+  delete pkg.devDependencies.autoprefixer;
+  // Add v4 deps
+  pkg.devDependencies.tailwindcss = '^4.0.0';
+  pkg.devDependencies['@tailwindcss/postcss'] = '^4.0.0';
+  pkg.devDependencies.postcss = '^8.4.47';
+
+  await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2));
+
+  // 2) Write PostCSS config for v4
+  await fs.outputFile(
+    path.join(dest, 'postcss.config.mjs'),
+    `export default { plugins: { '@tailwindcss/postcss': {} } };`
+  );
+
+  // 3) Inject the v4 CSS entry at the TOP of globals.css
+  const globalsPath = path.join(dest, 'src', 'app', 'globals.css');
+  const css = (await fs.pathExists(globalsPath)) ? await fs.readFile(globalsPath, 'utf8') : '';
+  const hasImport = /@import\s+["']tailwindcss["'];?/.test(css);
+  const withImport = hasImport ? css : `@import "tailwindcss";\n${css}`;
+  await fs.outputFile(globalsPath, withImport);
+
+  // 4) Make sure there is NO tailwind.config.* (v4 is zero-config)
+  const tcfgTs = path.join(dest, 'tailwind.config.ts');
+  const tcfgJs = path.join(dest, 'tailwind.config.js');
+  if (await fs.pathExists(tcfgTs)) await fs.remove(tcfgTs);
+  if (await fs.pathExists(tcfgJs)) await fs.remove(tcfgJs);
+}
+
+async function installDeps(pm, cwd) {
+  const args = ['install']; // install from package.json
+  await execa(pm, args, { cwd, stdio: 'inherit' });
+}
+
+async function main() {
+  const cli = cac('quickstart-next');
+  cli
+    .option('--preset <name>', 'base | tailwind')
+    .option('--pm <pm>', 'npm | pnpm | yarn | bun')
+    .option('--no-git', 'Skip git init')
+    .option('--no-install', 'Skip dependency install');
+  const { options } = cli.parse();
+
+  p.intro(green('Create Next.js project'));
+
+  const name = await p.text({
+    message: 'Project name?',
+    placeholder: 'my-next-app',
+    validate: v => (!v ? 'Required' : undefined)
+  });
+
+  const preset = options.preset || await p.select({
+    message: 'Choose a preset',
+    options: [
+      { label: 'Base (MUI, RHF, React Query)', value: 'base' },
+      { label: 'Tailwind v4 (Base + Tailwind)', value: 'tailwind' }
+    ]
+  });
+
+  const pm = options.pm || await p.select({
+    message: 'Package manager?',
+    options: [
+      { label: 'pnpm', value: 'pnpm' },
+      { label: 'npm', value: 'npm' },
+      { label: 'yarn', value: 'yarn' },
+      { label: 'bun', value: 'bun' }
+    ]
+  });
+
+  const dest = path.resolve(process.cwd(), name);
+  if (await fs.pathExists(dest) && (await fs.readdir(dest)).length) {
+    p.cancel('Target folder is not empty.');
+    process.exit(1);
+  }
+
+  const sp = ora(`Scaffolding ${cyan(name)} with ${yellow(preset)}...`).start();
+  await fs.copy(TEMPLATE_DIR, dest);
+
+  // set package name
+  const pkgPath = path.join(dest, 'package.json');
+  const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
+  pkg.name = name;
+  await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2));
+  sp.succeed('Files ready');
+
+  // Tailwind v4 augmentation
+  if (preset === 'tailwind') {
+    const tw = ora('Adding Tailwind v4...').start();
+    await addTailwindV4(dest);
+    tw.succeed('Tailwind v4 wired');
+  }
+
+  if (options.git !== false) {
+    await execa('git', ['init'], { cwd: dest });
+    await execa('git', ['add', '.'], { cwd: dest });
+    await execa('git', ['commit', '-m', 'chore: initial commit'], { cwd: dest });
+  }
+
+  if (options.install !== false) {
+    const inst = ora('Installing dependencies...').start();
+    await installDeps(pm, dest);
+    inst.succeed('Dependencies installed');
+  }
+
+  p.outro(`Done! Next steps:
+  1) cd ${name}
+  2) ${pm} run dev
+  `);
+}
+
+main();

package/templates/base/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+    "extends": ["next", "prettier"]
+  }

package/templates/base/.prettierrc.js

@@ -0,0 +1,19 @@
+// .prettierrc.js
+module.exports = {
+    arrowParens: 'avoid',
+    bracketSpacing: true,
+    htmlWhitespaceSensitivity: 'css',
+    insertPragma: false,
+    bracketSameLine: false,
+    jsxSingleQuote: true,
+    printWidth: 120,
+    proseWrap: 'preserve',
+    quoteProps: 'as-needed',
+    requirePragma: false,
+    semi: false,
+    singleQuote: true,
+    tabWidth: 2,
+    trailingComma: 'none',
+    useTabs: false
+  }
+  

package/templates/base/.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+    "editor.formatOnSave": true,
+    "[javascript]": {
+      "editor.defaultFormatter": "esbenp.prettier-vscode"
+    },
+    "[typescript]": {
+      "editor.defaultFormatter": "esbenp.prettier-vscode"
+    },
+    "[json]": {
+      "editor.defaultFormatter": "esbenp.prettier-vscode"
+    }
+  }
+  

package/templates/base/README.md

@@ -0,0 +1 @@
+## Next.js Template

package/templates/base/app/globals.css

@@ -0,0 +1,2 @@
+:root { --bg:#0b0b0f; --fg:#e3e3e7; }
+body { background:var(--bg); color:var(--fg); }

package/templates/base/app/layout.tsx

@@ -0,0 +1,33 @@
+import type { Metadata } from 'next'
+import { Geist, Geist_Mono } from 'next/font/google'
+import './globals.css'
+import BaseProviders from '@/providers/BaseProvider'
+
+const geistSans = Geist({
+  variable: '--font-geist-sans',
+  subsets: ['latin']
+})
+
+const geistMono = Geist_Mono({
+  variable: '--font-geist-mono',
+  subsets: ['latin']
+})
+
+export const metadata: Metadata = {
+  title: 'Create Next App',
+  description: 'Generated by create next app'
+}
+
+export default function RootLayout({
+  children
+}: Readonly<{
+  children: React.ReactNode
+}>) {
+  return (
+    <html lang='en'>
+      <body className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
+        <BaseProviders>{children}</BaseProviders>
+      </body>
+    </html>
+  )
+}

package/templates/base/app/page.tsx

@@ -0,0 +1,315 @@
+'use client'
+
+import * as React from 'react'
+import Link from 'next/link'
+import { Link as MuiLink } from '@mui/material'
+import {
+  Box,
+  Button,
+  Card,
+  CardContent,
+  Chip,
+  Container,
+  Divider,
+  Grid,
+  Stack,
+  Tooltip,
+  Typography
+} from '@mui/material'
+import ContentCopyIcon from '@mui/icons-material/ContentCopy'
+import OpenInNewIcon from '@mui/icons-material/OpenInNew'
+import { Github, Package, LayoutDashboard, FormInput } from 'lucide-react'
+import { Icon } from '@iconify/react'
+
+const Code = ({ children }: { children: React.ReactNode }) => (
+  <Box
+    component='code'
+    sx={{
+      display: 'inline-flex',
+      alignItems: 'center',
+      gap: 1,
+      px: 1.25,
+      py: 0.75,
+      borderRadius: 1,
+      bgcolor: 'rgba(255,255,255,0.08)',
+      border: '1px solid rgba(255,255,255,0.12)',
+      fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
+      fontSize: 14
+    }}
+  >
+    {children}
+  </Box>
+)
+
+export default function Page() {
+  const [copied, setCopied] = React.useState(false)
+
+  const handleCopy = async (text: string) => {
+    try {
+      await navigator.clipboard.writeText(text)
+      setCopied(true)
+      setTimeout(() => setCopied(false), 1200)
+    } catch {
+      // noop
+    }
+  }
+
+  return (
+    <Box
+      sx={{
+        minHeight: '100dvh',
+        position: 'relative',
+        overflow: 'hidden',
+        bgcolor: 'background.default',
+        color: 'text.primary'
+      }}
+    >
+      {/* --- Glowing blobs --- */}
+      <Box
+        aria-hidden
+        sx={{
+          pointerEvents: 'none',
+          position: 'absolute',
+          inset: 0,
+          '&::before, &::after': {
+            content: '""',
+            position: 'absolute',
+            width: 520,
+            height: 520,
+            borderRadius: '50%',
+            filter: 'blur(80px)',
+            opacity: 0.22,
+            transform: 'translate(-30%, -20%)',
+            background: 'radial-gradient(closest-side, #7C4DFF, transparent 70%)',
+            animation: 'float1 16s ease-in-out infinite'
+          },
+          '&::after': {
+            right: -120,
+            bottom: -120,
+            left: 'auto',
+            top: 'auto',
+            width: 620,
+            height: 620,
+            opacity: 0.18,
+            transform: 'translate(20%, 10%)',
+            background: 'radial-gradient(closest-side, #00E5FF, transparent 70%)',
+            animation: 'float2 18s ease-in-out infinite'
+          },
+          '@keyframes float1': {
+            '0%, 100%': { transform: 'translate(-30%, -20%) scale(1)' },
+            '50%': { transform: 'translate(-10%, -10%) scale(1.08)' }
+          },
+          '@keyframes float2': {
+            '0%, 100%': { transform: 'translate(20%, 10%) scale(1)' },
+            '50%': { transform: 'translate(10%, 20%) scale(0.95)' }
+          }
+        }}
+      />
+
+      <Container maxWidth='lg' sx={{ position: 'relative', zIndex: 1, py: { xs: 6, md: 10 } }}>
+        {/* Hero */}
+        <Stack spacing={3} alignItems='center' textAlign='center' sx={{ mb: { xs: 6, md: 10 } }}>
+          <Stack direction='row' spacing={1} alignItems='center'>
+            <LayoutDashboard size={28} style={{ verticalAlign: 'middle' }} />
+            <Typography variant='h4' fontWeight={800} letterSpacing={0.2} sx={{ ml: 1 }}>
+              Quickstart Next
+            </Typography>
+          </Stack>
+
+          <Typography variant='h6' sx={{ maxWidth: 860, opacity: 0.9 }}>
+            A modern Next.js boilerplate powered by <b>MUI</b> with room for <b>React Query</b>, <b>React Hook Form</b>,
+            and optional <b>Tailwind&nbsp;v4</b>.
+          </Typography>
+
+          <Stack direction={{ xs: 'column', sm: 'row' }} spacing={1.5} useFlexGap flexWrap='wrap'>
+            <Chip
+              icon={<Icon icon='simple-icons:mui' width={18} height={18} style={{ borderRadius: 4 }} />}
+              label='MUI'
+              color='primary'
+              variant='filled'
+            />
+            <Chip icon={<FormInput size={18} />} label='React Hook Form' variant='outlined' />
+            <Chip
+              icon={<Icon icon='devicon:tailwindcss' width={18} height={18} />}
+              label='Tailwind v4 (optional)'
+              variant='outlined'
+            />
+            <Chip
+              icon={<Icon icon='devicon:typescript' width={18} height={18} style={{ borderRadius: 4 }} />}
+              label='TypeScript'
+              variant='outlined'
+            />
+            <Chip icon={<Icon icon='devicon:nextjs' width={18} height={18} />} label='App Router' variant='outlined' />
+          </Stack>
+
+          <Stack direction={{ xs: 'column', sm: 'row' }} spacing={2} sx={{ pt: 1 }}>
+            <Button size='large' variant='contained' component={Link} href='/sample-form'>
+              Open Sample Form
+            </Button>
+            <Button
+              size='large'
+              variant='outlined'
+              endIcon={<OpenInNewIcon />}
+              component={Link}
+              href='#'
+              target='_blank'
+              rel='noopener'
+            >
+              View Docs
+            </Button>
+          </Stack>
+        </Stack>
+
+        {/* Content */}
+        <Grid container spacing={3}>
+          <Grid size={{ xs: 12, md: 7 }}>
+            <Card
+              sx={{
+                backdropFilter: 'saturate(120%) blur(6px)',
+                background: 'rgba(255,255,255,0.04)',
+                border: '1px solid',
+                borderColor: 'rgba(255,255,255,0.08)'
+              }}
+            >
+              <CardContent>
+                <Typography variant='h6' fontWeight={700} gutterBottom>
+                  What’s included
+                </Typography>
+                <Stack spacing={1.25} sx={{ opacity: 0.9 }}>
+                  <Typography>• Next.js 15 (App Router) + TypeScript</Typography>
+                  <Typography>• MUI ThemeProvider + dark-ready UI</Typography>
+                  <Typography>
+                    • RHF starter form at <code>/sample-form</code>
+                  </Typography>
+                  <Typography>• Easy opt-in Tailwind v4 (via CLI preset)</Typography>
+                </Stack>
+
+                <Divider sx={{ my: 3 }} />
+
+                <Typography variant='subtitle2' gutterBottom>
+                  Scaffold via npx
+                </Typography>
+
+                <Stack direction={{ xs: 'column', sm: 'row' }} spacing={1.5} alignItems='center'>
+                  <Code>npx @hadi87s/quickstart-next@latest</Code>
+                  <Tooltip title={copied ? 'Copied!' : 'Copy'}>
+                    <Button
+                      variant='outlined'
+                      size='small'
+                      startIcon={<ContentCopyIcon fontSize='small' />}
+                      onClick={() => handleCopy('npx @hadi87s/quickstart-next@latest')}
+                    >
+                      {copied ? 'Copied' : 'Copy'}
+                    </Button>
+                  </Tooltip>
+                </Stack>
+              </CardContent>
+            </Card>
+          </Grid>
+
+          <Grid size={{ xs: 12, md: 5 }}>
+            <Card
+              sx={{
+                height: '100%',
+                backdropFilter: 'saturate(120%) blur(6px)',
+                background: 'rgba(255,255,255,0.04)',
+                border: '1px solid',
+                borderColor: 'rgba(255,255,255,0.08)'
+              }}
+            >
+              <CardContent>
+                <Typography variant='h6' fontWeight={700} gutterBottom>
+                  Tech Logos
+                </Typography>
+                <Stack direction='row' spacing={2} alignItems='center' sx={{ pb: 1.5 }}>
+                  <Tooltip title='MUI' arrow placement='top'>
+                    <span>
+                      <Icon icon='simple-icons:mui' width={28} height={28} style={{ borderRadius: 4 }} />
+                    </span>
+                  </Tooltip>
+                  <Tooltip title='Tailwind CSS' arrow placement='top'>
+                    <span>
+                      <Icon icon='devicon:tailwindcss' width={28} height={28} />
+                    </span>
+                  </Tooltip>
+                  <Tooltip title='React' arrow placement='top'>
+                    <span>
+                      <Icon icon='devicon:react' width={28} height={28} />
+                    </span>
+                  </Tooltip>
+                  <Tooltip title='Next.js' arrow placement='top'>
+                    <span>
+                      <Icon icon='devicon:nextjs' width={28} height={28} />
+                    </span>
+                  </Tooltip>
+                  <Tooltip title='React Hook Form' arrow placement='top'>
+                    <span>
+                      <Icon icon='simple-icons:reacthookform' width={28} height={28} />
+                    </span>
+                  </Tooltip>
+                  <Tooltip title='TypeScript' arrow placement='top'>
+                    <span>
+                      <Icon icon='devicon:typescript' width={28} height={28} style={{ borderRadius: 4 }} />
+                    </span>
+                  </Tooltip>
+                </Stack>
+
+                <Typography variant='body2' sx={{ opacity: 0.85 }}>
+                  This template ships with MUI by default. You can enable Tailwind v4 at scaffold time. React Query and
+                  other integrations can be added as the stack grows.
+                </Typography>
+
+                <Divider sx={{ my: 2 }} />
+
+                <Stack direction='row' spacing={1.5}>
+                  <Button
+                    variant='outlined'
+                    size='small'
+                    startIcon={<Github size={18} />}
+                    endIcon={<OpenInNewIcon />}
+                    component={Link}
+                    href='https://github.com/hadi87s/quickstart-next'
+                    target='_blank'
+                    rel='noopener'
+                  >
+                    GitHub
+                  </Button>
+                  <Button
+                    variant='outlined'
+                    size='small'
+                    startIcon={<Package size={18} />}
+                    endIcon={<OpenInNewIcon />}
+                    component={Link}
+                    href='https://www.npmjs.com/package/@hadi87s/quickstart-next'
+                    target='_blank'
+                    rel='noopener'
+                  >
+                    npm
+                  </Button>
+                </Stack>
+              </CardContent>
+            </Card>
+          </Grid>
+        </Grid>
+
+        {/* Footer */}
+        <Stack alignItems='center' sx={{ mt: 8, opacity: 0.65 }}>
+          <Typography variant='body2'>
+            Built with ❤️ by{' '}
+            <MuiLink
+              href='https://github.com/hadi87s/quickstart-next'
+              underline='none'
+              color='primary'
+              sx={{ fontWeight: 600 }}
+              target='_blank'
+              rel='noopener'
+            >
+              Hadi
+            </MuiLink>{' '}
+            using MUI. Ready for Tailwind v4, React Query, and more.
+          </Typography>
+        </Stack>
+      </Container>
+    </Box>
+  )
+}

package/templates/base/eslint.config.mjs

@@ -0,0 +1,16 @@
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+});
+
+const eslintConfig = [
+  ...compat.extends("next/core-web-vitals", "next/typescript"),
+];
+
+export default eslintConfig;

package/templates/base/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;