Co-Operability.com

My Next.js portfolio website on Vercel. Several smaller projects within.

TODO:

• OC input fields block numbers but should pop up numpad on mobile
• SEO; site:cooperability.com
• Create .editorconfig for consistency
• Add .npmrc for Yarn users
• commitlint for commit messages
• cursorrules for cursor

Developer Tooling

This project uses a comprehensive suite of quality control tools. For complete documentation, see docs/Tooling.md.

Quick Reference:

• yarn dev - Start development server
• yarn lint / yarn lint:mdx - ESLint checking (includes MDX validation)
• yarn format / yarn format:mdx - Prettier formatting
• yarn test - Jest + React Testing Library
• yarn typecheck - TypeScript validation
• yarn analyze - Webpack bundle analysis
• yarn access - Accessibility audits (ESLint + Axe-core + Lighthouse)
• yarn audit / yarn audit:critical - Security vulnerability scanning

Security: Pre-push hooks and GitHub Actions block vulnerable code. See docs/Tooling.md#security-auditing.

Key Technologies:

• Linting: ESLint with TypeScript, Next.js, and MDX support
• Formatting: Prettier with automatic MDX prose wrapping
• Testing: Jest with @testing-library/react and jest-dom matchers
• Automation: Husky (pre-commit + pre-push security), lint-staged, GitHub Actions
• Package Management: Yarn Plug'n'Play (PnP) for zero-install, deterministic dependencies
• UI Components: shadcn/ui (Tailwind + Radix UI primitives)
• Bundle Analysis: Webpack Bundle Analyzer for optimization
• Accessibility: Automated testing with axe-core CLI and Lighthouse
• Icons: skillicons.dev (theme-aware tech stack icons via simple-icons.org)

See docs/Tooling.md for setup instructions, troubleshooting, and best practices.

Performance & Responsive Design

This project implements comprehensive performance optimizations and a content-first responsive design strategy:

Performance:

• Dynamic imports with disabled SSR for heavy components (~85KB bundle reduction)
• Loading skeletons to prevent CLS (Cumulative Layout Shift)
• Debounced resize handling (100ms) for smooth responsiveness
• Fluid spacing with CSS clamp() for breakpoint-free scaling

Responsive Design:

• Primary breakpoint: 525px (useResponsive hook) for site-wide mobile/desktop splits
• Tailwind-aligned breakpoints: sm (640px), md (768px), lg (1024px), xl (1280px)
• Philosophy: Break where content naturally requires it, not at arbitrary device widths

See docs/Performance.md for complete optimization strategies, breakpoint implementation, and best practices.

Tech Stack Icons & SVG Configuration

This project uses skillicons.dev for theme-aware technology stack icons on the demos page. These icons automatically adapt to light/dark theme and provide consistent, professional styling.

Implementation:

• Icons source from simple-icons.org via skillicons.dev API
• Dynamic theme switching via next-themes integration
• Fallback to custom PNGs for unavailable icons (shadcn/ui, Poetry)

Security Configuration (next.config.js):

// next.config.js
module.exports = {
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: 'skillicons.dev', pathname: '/icons/**' },
    ],
    dangerouslyAllowSVG: true,
    contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
  },
}

Security Measures:

• ✅ dangerouslyAllowSVG enables external SVG loading (required for skillicons.dev)
• ✅ CSP blocks script execution: script-src 'none' prevents XSS attacks
• ✅ Sandbox environment limits SVG capabilities
• ✅ Trusted source only (skillicons.dev domain restriction)
• ✅ Follows Vercel's official security recommendations

Benefits:

• Automatic light/dark theme adaptation
• Consistent color grading across all tech icons
• Professional, scalable vector graphics
• Single source of truth for icon styling

Trade-offs:

• Requires external domain allowlist for SVGs
• Minor dependency on third-party service (skillicons.dev)
• Some icons unavailable (resolved with custom fallbacks)

Privacy Policy, SEO, Analytics

• Privacy: Privacy-forward Next Analytics is used instead of Google Analytics for better anonymization.
• SEO: See docs/SEO.md

Project Dependencies

Runtime Dependencies (dependencies)

• @heroicons/react: SVG icons as React components.
• @mdx-js/loader: Webpack loader for MDX files.
• @mdx-js/react: React components for rendering MDX.
• @next/mdx: Integration for using MDX with Next.js.
• @tailwindcss/typography: Tailwind plugin for beautiful typography defaults.
• @vercel/analytics: Vercel integration for website analytics.
• @vercel/speed-insights: Vercel integration for performance monitoring.
• date-fns: Modern JavaScript date utility library.
• gray-matter: Parses front-matter from files (e.g., Markdown metadata).
• next: The React framework for production.
• next-mdx-remote: Renders MDX content dynamically in Next.js.
• next-themes: Theme switching support for Next.js apps.
• prop-types: Runtime type checking for React props.
• react: JavaScript library for building user interfaces.
• react-dom: Serves as the entry point to the DOM and server renderers for React.
• remark: Markdown processor.
• remark-html: Plugin for remark to serialize Markdown to HTML.
• sharp: High-performance Node.js image processing library.

Development Dependencies (devDependencies)

• @eslint/compat: Compatibility utilities for ESLint flat config.
• @eslint/eslintrc: Utilities for using .eslintrc configs with flat config.
• @eslint/js: Core JavaScript rules for ESLint.
• @types/node: TypeScript definitions for Node.js.
• @types/react: TypeScript definitions for React.
• autoprefixer: PostCSS plugin to parse CSS and add vendor prefixes.
• cross-env: Sets environment variables cross-platform for scripts.
• eslint: Pluggable linting utility for JavaScript and JSX/TSX.
• eslint-config-next: Standard ESLint configuration for Next.js projects.
• eslint-config-prettier: Disables ESLint rules that conflict with Prettier.
• husky: Manages Git hooks to automate tasks.
• lint-staged: Runs linters against staged Git files.
• postcss: Tool for transforming CSS with JavaScript plugins.
• postcss-import: PostCSS plugin to inline @import rules.
• prettier: Opinionated code formatter.
• tailwindcss: Utility-first CSS framework.
• typescript: Typed superset of JavaScript that compiles to plain JavaScript.
• typescript-eslint: Tooling which enables ESLint to lint TypeScript code.

Resources I used to build this website

Light/Dark Mode Button in NextJS
Tailwind with Next
Server-side rendering a random number
Adding analytics with Vercel
Changing the site's icon
something to explain mobile compatibility Vercel Observability; Vercel Analytics Jest Testing in Next.js Cross-platform Favicon Generation

---

Development Learnings

Detailed learnings from this project are documented in their respective locations:

Topic	Documentation
CSS Modules & Theming	docs/Tooling.md
Tailwind Troubleshooting	docs/Tooling.md
MDX Component Integration	docs/Tooling.md
Case Sensitivity (Windows/Linux)	docs/Tooling.md
Performance & Responsive Design	docs/Performance.md
Unified Link Components	docs/PROJECT-STRUCTURE.md
Mobile Table Refinement	src/components/opioid-converter/OPIOID-CONVERTER-README.md

---

Accessibility

This project follows WCAG 2.1 AA standards with automated testing via ESLint, Axe-core, and Lighthouse.

Run audits: yarn access (saves reports to ./accessibility-reports/)

Completed Features:

• ✅ Semantic HTML5 and proper heading hierarchy
• ✅ Keyboard navigation and focus management
• ✅ ARIA attributes for screen readers
• ✅ WCAG AA color contrast (light and dark themes)
• ✅ Automated testing suite integrated into development workflow

Maintenance Tasks:

• Explore Playwright + Axe-core for CI-integrated theme testing
• Ensure all iconic buttons have discernible screen reader text
• Regular WCAG compliance reviews

See docs/Tooling.md#accessibility-testing for detailed testing procedures.

PWA & App-like Experience

This project implements a comprehensive PWA applet suite - transforming individual tools into installable Progressive Web Apps with their own identities while sharing infrastructure. Each applet (Prompt Composer, Opioid Converter) can be added to a mobile home screen as a separate app with its own name.

📚 Complete Documentation: docs/PWA.md

This comprehensive guide covers everything from PWA basics to advanced implementation:

• What PWAs are and how they work
• The applet suite architecture and philosophy
• Step-by-step implementation guide
• Testing procedures (iOS, Android, desktop)
• Troubleshooting common issues
• Advantages, disadvantages, and trade-offs
• Future enhancement opportunities

Quick Overview

Status: ✅ Fully implemented (January 2025)

Implemented Applets:

• "Prompt Composer" - Installs as standalone app from /prompt-composer
• "Opioid Converter" - Installs as standalone app from /opioid-converter
• "Co-Operability" - Main portfolio with shortcuts to applets

Key Features:

• ✅ Each applet has unique installable identity
• ✅ Shared service worker (efficient caching)
• ✅ Same icon set (brand consistency)
• ✅ iOS and Android support
• ✅ Offline-capable via Serwist (Workbox successor)

Technology Stack:

• Service Worker: Serwist (migrated from deprecated next-pwa)
• Build Process: next build → build-sw.mjs → next-sitemap
• Files: src/sw.js (source) → public/sw.js (compiled)

Next Steps:

• Custom icons per applet
• Enhanced offline functionality
• Deep linking & share targets
• App store distribution (Microsoft Store, Google Play via TWA)

See docs/PWA.md for complete implementation guide, testing procedures, and troubleshooting.

Package Management (Yarn PnP)

This project uses Yarn Plug'n'Play (PnP) for zero-install, deterministic dependency resolution.

Benefits:

• ✅ Faster CI (smaller checkouts)
• ✅ Deterministic resolution (no phantom packages)
• ✅ Better editor integration via Yarn SDKs

One-time setup after cloning:

yarn dlx @yarnpkg/sdks vscode  # or vim, intellij, etc.

Important Files:

• .pnp.cjs - PnP manifest (commit to git)
• .yarn/sdks/** - Editor wrappers (commit to git)
• .yarnrc.yml - Yarn configuration

Upgrading Yarn:

yarn set version 4.10.3
corepack prepare yarn@4.10.3 --activate
yarn install && yarn dedupe --strategy=highest

See docs/Tooling.md#yarn-plugnplay-pnp for troubleshooting and Vercel deployment details.