🌐 Aleksandar Kitipov Portfolio Foundation

This repository now contains a Vite-powered React TypeScript foundation for the kitipov.net GitHub Pages site. The current milestone intentionally focuses on the project scaffold and deployment baseline rather than the final visual design.

✅ Current stack

• Vite for local development and static production builds
• React with TypeScript for the application layer
• Optimized SVG visual assets and motion-safe CSS for production performance
• GitHub Pages-compatible static output through the dist/ directory
• Custom domain support through public/CNAME

📁 Project structure

.
├── .github/workflows/         # CI quality checks and GitHub Pages deployment
├── coverage/                   # Generated by npm run test:coverage (not committed)
├── docs/legacy/                # Archived static HTML version for reference
│   ├── index.html
│   ├── about.html
│   ├── contacts.html
│   ├── links.html
│   └── screenshots/            # Archived screenshots from the previous site
├── public/
│   └── CNAME                   # Copied into dist/ during Vite builds
├── src/
│   ├── assets/images/          # Optimized app-owned image assets
│   ├── styles/globals.css      # Global application styles
│   ├── App.tsx
│   ├── main.tsx
│   └── vite-env.d.ts
├── tests/                      # Component, route smoke, SEO, and accessibility checks
├── index.html                  # Vite HTML entry point
├── netlify.toml                # Netlify static deploy and SPA fallback
├── package.json
├── render.yaml                 # Render static deploy configuration
├── tsconfig.json
├── vercel.json                 # Vercel static deploy and SPA fallback
├── tsconfig.node.json
└── vite.config.ts

🚀 Getting started

Install dependencies:

npm install

Start the local development server:

npm run dev

Windows native binding troubleshooting

This project pins Vite to the latest Vite 7 line instead of using latest. Vite 8 switched core development/build internals to Rolldown/Oxc native packages, and the Windows native Rolldown binding can fail to load with errors such as Cannot find native binding or ERR_DLOPEN_FAILED on some machines.

If you previously installed dependencies while vite was set to latest, clear the generated install artifacts and reinstall so npm resolves the pinned versions from package.json:

Remove-Item -Recurse -Force node_modules, package-lock.json -ErrorAction SilentlyContinue
npm install
npm run dev

Use Node.js 20.19+ or newer. The hosted build configurations use Node 22 where a host-specific Node version is required.

Build the static site:

npm run build

Preview the production build locally:

npm run preview

🧪 Code quality scripts

Use these checks before opening feature or content pull requests. For production polish PRs, also inspect the built dist/ assets and run Lighthouse against a local preview or the selected hosting provider:

npm run lint
npm run format:check
npm run typecheck
npm run test
npm run test:coverage

Available quality scripts:

• npm run lint runs ESLint across the TypeScript and React source files with baseline rules for correctness, React Hooks, and Fast Refresh-friendly exports.
• npm run format:check verifies that tracked project files match the Prettier configuration without modifying them.
• npm run format applies Prettier formatting when a check reports differences.
• npm run typecheck runs the TypeScript compiler in --noEmit mode so type errors are caught before builds.
• npm run test runs the component, route smoke, accessibility, and SEO checks under tests/.
• npm run test:coverage runs the same checks and writes a lightweight coverage report to coverage/index.html plus coverage/coverage-summary.json.

npm run build also runs npm run typecheck before creating the Vite production bundle.

⚡ Production performance checklist

• Visual backgrounds should stay in src/assets/images/ as compressed SVG/WebP/AVIF assets sized for their rendered use. The current abstract background is a 2 KB SVG rather than the previous 1.3 MB raster.
• Navigation and content spacing include mobile-first fallbacks, horizontal overflow handling for small screens, and safe-area padding for modern mobile browsers.
• Global transitions are disabled under prefers-reduced-motion: reduce so hover polish does not become motion for users who opt out.
• Before release, run npm run build, preview the generated dist/ output, and target Lighthouse scores of Performance 90+, Accessibility 95+, Best Practices 95+, and SEO 95+ on the chosen hosting provider.

🚢 Deployment

All production builds are generated with Vite and published from dist/:

npm install
npm run build

Before changing DNS, choose a single production host to own the canonical kitipov.net records. Do not point the same production hostname at GitHub Pages, Render, Vercel, and Netlify at the same time.

GitHub Pages

This repository includes .github/workflows/deploy-github-pages.yml, which builds the site on pushes to main and deploys the generated dist/ artifact with GitHub's Pages actions.

1. In GitHub, open Settings → Pages.
2. Set Source to GitHub Actions.
3. Confirm public/CNAME contains kitipov.net; Vite copies it to dist/CNAME during the workflow.
4. Push to main or run the Deploy GitHub Pages workflow manually from the Actions tab.

Render

render.yaml declares a static web service for Render:

• Build command: npm install && npm run build
• Publish directory: dist
• SPA fallback: /* rewrites to /index.html

Create or sync the Render service from the Blueprint, then configure custom-domain DNS in the Render dashboard if Render is the chosen canonical host.

Vercel

vercel.json configures Vercel for a Vite static deployment:

• Install command: npm install
• Build command: npm run build
• Output directory: dist
• SPA fallback: all routes rewrite to /index.html

Import the repository in Vercel and configure kitipov.net DNS in the Vercel dashboard only if Vercel is the canonical production host.

Netlify

netlify.toml configures Netlify for the same static build:

• Build command: npm run build
• Publish directory: dist
• Node version: 22
• SPA fallback: /* returns /index.html with status 200

Import the repository in Netlify and configure custom-domain DNS in the Netlify dashboard only if Netlify is the canonical production host.

Quality workflow

.github/workflows/quality.yml runs on pull requests and pushes to main. It installs dependencies and executes npm run ci:quality, which chains linting, type checking, tests, and the production build.

🌍 Domain and GitHub Pages notes

• Custom domain: kitipov.net
• The root CNAME file is retained for domain reference.
• public/CNAME is the deployment source of truth for Vite builds because files in public/ are copied directly into dist/.
• After running npm run build, confirm dist/CNAME exists before publishing the build output to GitHub Pages.

🧭 Legacy archive

The original static site files were moved to docs/legacy/ instead of being deleted. This keeps the previous HTML-only implementation available for review while allowing the root index.html to become the Vite entry point.

Archived files:

• docs/legacy/index.html
• docs/legacy/about.html
• docs/legacy/contacts.html
• docs/legacy/links.html
• docs/legacy/screenshots/

The previous heavy raster background was replaced by src/assets/images/background.svg, a lightweight optimized SVG imported through the global stylesheet.

📜 License

This project is released under the MIT License.