create-foliokit 1.0.0 → 1.0.1

package/README.md

@@ -1,378 +1,112 @@
-# FolioKit
+# 🚀 FolioKit
 
+[![npm](https://img.shields.io/npm/v/create-foliokit.svg)](https://www.npmjs.com/package/create-foliokit)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.12.0-brightgreen.svg)](package.json)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22.12.0-brightgreen.svg)](package.json)
-[![npm version](https://img.shields.io/npm/v/foliokit.svg)](https://www.npmjs.com/package/foliokit)
 
-> A modern, zero-config CLI generator that scaffolds high-performance, customizable developer portfolios built with React 19, TypeScript, and Vite.
+FolioKit is a CLI for creating a customizable developer portfolio. It scaffolds a responsive **React 19**, **TypeScript**, and **Vite** website with a dark grid background, framed sections, social links, and an interactive project gallery.
 
-FolioKit enables developers to launch a sleek, production-ready portfolio in seconds. Instead of wrestling with complex UI code, your entire website—from bio and skills to featured projects and social links—is managed cleanly through a single configuration file: [`data.ts`](templates/default/data.ts).
+Created and maintained by [Saurabh Pandey](https://github.com/saurabhhdev) · [GitHub repository](https://github.com/saurabhhdev/foliokit)
 
 ---
 
-## Features
+## ✨ Make It Yours
 
-- **Instant Scaffolding** — Create a complete portfolio project with one command (`npx foliokit`).
-- **Single-File Customization** — Edit `data.ts` to update all content, projects, bio, skills, and layout ordering without touching React components.
-- **Modern Tech Stack** — Built with React 19, TypeScript, and Vite for fast development and lightweight production bundles (~80 kB gzip).
-- **Aesthetic Obsidian Theme** — Designed with a dark graphite palette, atmospheric canvas starfields, and metallic typography accents.
-- **Interactive 3D Magazine Carousel** — Showcase featured projects in a perspective-lifted cover gallery with mouse-tilt, touch swipe, trackpad wheel gestures, and keyboard navigation.
-- **Automatic Skill Icons** — Integrates with [Skill Icons](https://skillicons.dev) and Simple Icons for crisp vector technology and brand badges.
-- **Dynamic Local Time & Clock** — Real-time digital clock synced to your configured IANA time zone.
-- **Pre-Configured Content Sections** — Hero, About, Skills, Featured Projects, Work Experience, Education, Testimonials, and Contact.
-- **Automated SEO & Social Sharing** — Build script automatically injects personalized OpenGraph tags, Twitter cards, canonical links, and generates a valid `sitemap.xml` and `robots.txt`.
-- **Accessible & Responsive** — Verified across mobile (320px+), tablet, laptop, and ultra-wide screens. Full support for `prefers-reduced-motion` and WCAG touch targets.
-- **Static Hosting Ready** — Zero-config static deployment on Vercel, Netlify, Cloudflare Pages, and GitHub Pages.
+Most portfolio content is edited in one file: `data.ts` in the generated project.
 
----
-
-## Preview
+| What | Where |
+| --- | --- |
+| Name, headline, bio, photo, location, time zone, resume | `data.ts` → `profile` |
+| Social profiles and links | `data.ts` → `socialIcons` |
+| Work history and organization logos | `data.ts` → `experience` |
+| Schools, programs, dates, locations | `data.ts` → `education` |
+| Skill names, icons, and categories | `data.ts` → `skills` |
+| Project details, screenshots, technologies, URLs | `data.ts` → `projects` |
+| Recommendations | `data.ts` → `testimonials` |
+| Contact email | `data.ts` → `contact` |
+| Browser and social preview metadata | `data.ts` → `seo` |
 
-<!-- Portfolio UI Preview Screenshot Placeholder -->
-<!-- Place your screenshot here: ![FolioKit Preview](https://raw.githubusercontent.com/saurabhhdev/foliokit/main/preview.png) -->
+Copy images into `public/` and use paths such as `'/my-photo.jpg'` in `data.ts`. The template includes avatar, project, and experience logo placeholders. Leave an optional section array empty (`[]`) to hide that section.
 
-The generated portfolio features a dark obsidian background (`#000000`), subtle starfield overlays, golden metallic accent highlights, and clean dotted framing inspired by modern developer terminals and developer tool aesthetic.
+Interface labels are beside the components in `src/App.tsx` and `src/ProjectMagazineGallery.tsx`. Colors, grid, spacing, and responsive styles are in `src/styles.css` and `src/ProjectMagazineGallery.css`.
 
 ---
 
-## Requirements
-
-Before running FolioKit, ensure your environment meets these requirements:
+## 🛠 Run Locally
 
-- **Node.js**: Version `22.12.0` or higher
-- **npm**: Version `10.0.0` or higher (or compatible `pnpm` / `yarn`)
-- **Operating Systems**: macOS, Linux, and Windows 10/11
-
-To verify your installed Node.js version, run:
+You need Node.js **22.12.0 or newer** to run the CLI. No global installation is required.
 
 ```bash
-node --version
-```
-
----
-
-## Quick Start
-
-Generate your developer portfolio in three steps:
-
-### 1. Run the CLI
-
-```bash
-npx foliokit
-```
-
-*Or install globally:*
-
-```bash
-npm install -g foliokit
-foliokit
+npx create-foliokit@latest
 ```
 
-### 2. Answer the Interactive Prompts
-
-```text
-FOLIOKIT
-Developer Portfolio Generator
-
-? What should your project be called? my-portfolio
-? Install dependencies? (Y/n) y
-```
-
-- **Project name**: Enter a folder name using lowercase letters, numbers, and single hyphens (default: `my-portfolio`).
-- **Install dependencies**: Choose whether FolioKit should automatically run `npm install` inside the created folder.
-
-### 3. Start Developing
+Choose a project folder name and whether to install dependencies. Then:
 
 ```bash
 cd my-portfolio
 npm run dev
 ```
 
-Open [http://localhost:5173](http://localhost:5173) in your browser to view your live portfolio.
-
----
-
-## CLI Commands & Options
+Open the local address printed by Vite, usually `http://localhost:5173`. If you skipped dependency installation, run `npm install` in the project folder first.
 
-FolioKit provides a straightforward command-line interface:
-
-| Command / Option | Description |
-| :--- | :--- |
-| `npx foliokit` | Runs the interactive project creation wizard in the current directory. |
-| `foliokit create` | Explicit subcommand to start the setup wizard. |
-| `-v, --version` | Outputs the current installed FolioKit version. |
-| `-h, --help` | Displays help information, available flags, and usage syntax. |
-
-### Examples
+To install the CLI globally instead:
 
 ```bash
-# Check installed CLI version
-foliokit --version
-
-# View usage guidelines
-foliokit --help
-
-# Create a new project
-foliokit create
-```
-
----
-
-## Customization Guide (`data.ts`)
-
-All portfolio content is centralized in the root `data.ts` file of your generated project. Open `data.ts` in your code editor to personalize your site.
-
-### 1. Personal Details & Hero
-
-```typescript
-profile: {
-  name: 'Alex Rivera',
-  headline: 'Full Stack Engineer & Open Source Contributor',
-  introduction: "Hey, there! I'm a",
-  about: `I build scalable web applications and developer tools.
-  
-I specialize in React, Node.js, and distributed systems.`,
-  location: 'San Francisco, CA',
-  timeZone: 'America/Los_Angeles',
-  timeZoneLabel: 'PST',
-  profileImage: '/avatar-placeholder.svg', // or '/my-photo.jpg' placed in public/
-  quote: 'Build with curiosity. Share what you learn.',
-}
-```
-
-### 2. Social Links
-
-Add or update your social media profiles in the `socialIcons` array:
-
-```typescript
-socialIcons: [
-  { label: 'GitHub', icon: 'github', url: 'https://github.com/your-username', color: '#f2f0e9' },
-  { label: 'LinkedIn', icon: 'linkedin', url: 'https://linkedin.com/in/your-username', color: '#0a66c2' },
-  { label: 'X', icon: 'x', url: 'https://x.com/your-username', color: '#f2f0e9' },
-]
-```
-
-### 3. Technical Skills
-
-Add, remove, or reorder technologies. Icons are automatically fetched from [Skill Icons](https://skillicons.dev) using the `icon` identifier:
-
-```typescript
-skills: [
-  { name: 'React', icon: 'react', category: 'Frontend' },
-  { name: 'TypeScript', icon: 'ts', category: 'Frontend' },
-  { name: 'Node.js', icon: 'nodejs', category: 'Backend' },
-  { name: 'PostgreSQL', icon: 'postgres', category: 'Backend' },
-  { name: 'Docker', icon: 'docker', category: 'Tools' },
-]
-```
-
-### 4. Featured Projects
-
-Projects with `featured: true` appear prominently in the interactive 3D magazine gallery as well as the detailed project cards below:
-
-```typescript
-projects: [
-  {
-    name: 'DevFlow',
-    category: 'DEVELOPER TOOLING',
-    description: 'An open-source terminal workflow engine designed to automate repetitive task pipelines.',
-    image: '/project-placeholder.svg', // Place your thumbnail in public/
-    imageAlt: 'DevFlow terminal preview',
-    technologies: [
-      { name: 'TypeScript', icon: 'ts' },
-      { name: 'Node.js', icon: 'nodejs' },
-    ],
-    liveUrl: 'https://devflow.example',
-    githubUrl: 'https://github.com/your-username/devflow',
-    featured: true,
-  },
-]
-```
-
-### 5. Work Experience & Education
-
-```typescript
-experience: [
-  {
-    title: 'Senior Software Engineer',
-    organization: 'Acme Corp',
-    date: '2023 – Present',
-    description: 'Architected microservices and improved core API latency by 35%.',
-  },
-],
-education: [
-  {
-    title: 'B.S. in Computer Science',
-    organization: 'University of California, Berkeley',
-    date: '2019 – 2023',
-    description: 'Focused on algorithms, distributed databases, and software engineering.',
-  },
-]
+npm install --global create-foliokit
+foliokit
 ```
 
-### 6. Optional Sections (Testimonials, Experience, Education)
+### Available commands
 
-Content sections render dynamically based on whether items exist in their array. To omit any optional section from the portfolio, simply leave its array empty:
-
-```typescript
-// Leave empty to omit this section from the portfolio:
-testimonials: [],
-experience: [],
-education: [],
-```
+| Command | Action |
+| --- | --- |
+| `foliokit` | Start the setup wizard. |
+| `foliokit create` | Start the wizard with the explicit `create` command. |
+| `foliokit --help` | Show CLI help. |
+| `foliokit --version` | Print the installed version. |
 
 ---
 
-## Images and Assets
+## 📦 Build and Deploy
 
-All static visual assets live inside the `public/` directory of your generated project:
+Run the generated portfolio's checks and create a production build:
 
-```text
-my-portfolio/
-└── public/
-    ├── avatar-placeholder.svg
-    ├── project-placeholder.svg
-    ├── footer-heart.png
-    ├── love-always-wins.png
-    └── robots.txt
+```bash
+npm test
+npm run build
+npm run preview
 ```
 
-### How to Use Your Own Images:
+Vite writes the static site to `dist/`. Deploy it to a static host such as **Vercel** or **Netlify** with build command `npm run build` and output directory `dist`.
 
-1. Copy your image into the `public/` folder (e.g. `public/my-photo.jpg`).
-2. In `data.ts`, reference the image with a leading slash:
-   ```typescript
-   profileImage: '/my-photo.jpg'
-   ```
-3. For project thumbnails, copy images to `public/` (recommended aspect ratio: `16:9` or `1200x675` px) and set `image: '/project-one.png'`.
-4. **Supported Formats**: SVG, WebP, PNG, JPG/JPEG.
-5. **Fallbacks**: If an image fails to load or is omitted, FolioKit automatically renders accessible fallback elements (e.g., initial-letter monogram badges for avatars).
+For canonical URLs and sitemap generation, set `SITE_URL` in the hosting environment to your HTTPS origin, for example `https://portfolio.example` (no path or query string). You can also set `seo.siteUrl` in `data.ts`.
 
 ---
 
-## Project Structure
+## 🧰 Stack and Project Files
 
-A portfolio generated by FolioKit has the following clean structure:
+The generated site uses React, TypeScript, Vite, Lucide icons, and CSS. The CLI package uses Commander, Inquirer, Chalk, and Ora.
 
 ```text
 my-portfolio/
-├── data.ts                   # Central content configuration (edit this!)
-├── index.html                # HTML entry point (title & metadata injected from data.ts)
-├── package.json              # Project scripts and dependencies
-├── vite.config.ts            # Vite configuration with automated metadata plugin
-├── tsconfig.json             # TypeScript configuration
-├── public/                   # Static assets (images, avatars, icons, robots.txt)
-│   ├── avatar-placeholder.svg
-│   └── project-placeholder.svg
-├── scripts/
-│   └── generate-seo.mjs      # Production SEO, canonical URL, and sitemap generator
+├── data.ts                 # Edit your portfolio content
+├── types.ts                # Shared TypeScript types
+├── public/                 # Images and robots.txt
+├── scripts/generate-seo.mjs
+├── tests/portfolio.test.js
 └── src/
-    ├── main.tsx              # React application entry point
-    ├── App.tsx               # Main portfolio layout and section renderers
-    ├── styles.css            # Responsive styles and theme variables
-    ├── utils.ts              # Lightweight DOM helpers
-    ├── BrandIcon.tsx         # Vector brand logo helper with fallbacks
-    ├── ProjectMagazineGallery.tsx  # 3D interactive carousel
-    └── ProjectMagazineGallery.css  # 3D perspective & carousel styling
+    ├── App.tsx
+    ├── BrandIcon.tsx
+    ├── ProjectMagazineGallery.tsx
+    ├── ProjectMagazineGallery.css
+    ├── styles.css
+    └── main.tsx
 ```
 
 ---
 
-## Tech Stack
-
-### FolioKit CLI
-- **Runtime**: [Node.js](https://nodejs.org) (>= 22.12.0)
-- **CLI Framework**: [Commander.js](https://github.com/tj/commander.js)
-- **Interactive Prompts**: [Inquirer.js](https://github.com/SBoudrias/Inquirer.js)
-- **Terminal Styling**: [Chalk](https://github.com/chalk/chalk)
-- **Terminal Spinners**: [Ora](https://github.com/sindresorhus/ora)
-
-### Generated Portfolio
-- **UI Framework**: [React 19](https://react.dev)
-- **Language**: [TypeScript](https://www.typescriptlang.org)
-- **Bundler & Dev Server**: [Vite 8](https://vitejs.dev)
-- **Icons**: [Lucide React](https://lucide.dev) & [Simple Icons](https://simpleicons.org)
-- **Styling**: Native Modern CSS (CSS Grid, Flexbox, CSS Variables, 3D Transforms)
-
----
-
-## Troubleshooting
-
-### 1. "Node.js version must be >=22.12.0"
-- **Cause**: An older Node.js runtime is active in your terminal.
-- **Solution**: Install or activate Node.js 22.12.0 or newer using [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm):
-  ```bash
-  nvm install 22
-  nvm use 22
-  ```
-
-### 2. Destination Folder Already Exists
-- **Cause**: A folder with the specified project name already exists in your current directory.
-- **Solution**: Choose a different name when prompted, or confirm the prompt to overwrite the existing folder.
-
-### 3. Dependency Installation Failed
-- **Cause**: Network timeout or strict corporate proxy blocked `npm install`.
-- **Solution**: Your generated project files are safely preserved. Navigate into the folder and manually install dependencies:
-  ```bash
-  cd my-portfolio
-  npm install
-  ```
-
-### 4. Development Port 5173 in Use
-- **Cause**: Another local development server is running on port 5173.
-- **Solution**: Vite automatically attempts the next available port (e.g. 5174). You can also specify a custom port:
-  ```bash
-  npm run dev -- --port 3000
-  ```
-
-### 5. TypeScript Error After Editing `data.ts`
-- **Cause**: A required field was removed or a type mismatch was introduced.
-- **Solution**: Check the terminal output or editor diagnostics. Run `npm test` inside the portfolio directory to validate your `data.ts` structure against the test suite.
-
----
-
-## Contributing
-
-Contributions, issues, and feature requests are welcome!
-
-### Development Workflow
-
-1. Fork the repository on GitHub.
-2. Clone your fork locally:
-   ```bash
-   git clone https://github.com/saurabhhdev/foliokit.git
-   cd foliokit
-   ```
-3. Install dependencies:
-   ```bash
-   npm install
-   ```
-4. Run CLI and generator tests:
-   ```bash
-   npm test
-   ```
-5. Test the default template:
-   ```bash
-   cd templates/default
-   npm test
-   npm run build
-   cd ../..
-   ```
-6. Create a feature branch (`git checkout -b feature/amazing-idea`), commit your changes, and submit a pull request.
-
----
-
-## License
-
-Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for complete details.
-
-Copyright (c) 2026 **Saurabh Pandey**.
-
----
+## 🙌 Contributing and License
 
-## Author & Links
+For CLI development, run `npm install` and `npm test` at the repository root. To check the bundled website template, run `npm test` and `npm run build` inside `templates/default/`.
 
-- **Author**: Saurabh Pandey
-- **GitHub**: [@saurabhhdev](https://github.com/saurabhhdev)
-- **Repository**: [https://github.com/saurabhhdev/foliokit](https://github.com/saurabhhdev/foliokit)
-- **Issue Tracker**: [https://github.com/saurabhhdev/foliokit/issues](https://github.com/saurabhhdev/foliokit/issues)
+FolioKit is open source under the [MIT License](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-foliokit",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Generate customizable React and TypeScript developer portfolios",
   "type": "module",
   "main": "./src/cli.js",