A Next.js web app for browsing and exploring community activities.

Live Demo: https://activity-finder-sigma.vercel.app

This project was created as a front-end take-home assignment for Illusian. It's a demo application that showcases:

• Modern React/Next.js development practices
• Component-driven development with Storybook
• Comprehensive testing strategies
• TypeScript and type-safe development

Important notes:

• No backend - all data is stored in mock JSON files
• No authentication - anyone can edit participant data by name
• Not production-ready (see Future Improvements for details)

📝 Read about my thinking process and decisions →

• Browse Activities - View a list of community activities with key details
• Activity Details - See full information including description, location, time and more
• Participant Management - Interactive signup and attendance tracking
• Availability Status - Display of available spots
• Responsive Design - Works on mobile and desktop devices

• Next.js 16 - React framework with App Router
• React 19 - UI library
• TypeScript 5 - Type-safe JavaScript
• Tailwind CSS 4 - Utility-first CSS framework
• Zod - Schema validation
• Vitest - Unit testing framework
• Storybook 10 - Component documentation and testing
• Motion - Animation library

• Node.js 20.0.0 or higher
• npm 10.0.0 or higher

Check your versions:

node --version
npm --version

# Install dependencies
npm install

# Run development server
npm run dev

Open http://localhost:3000 to view the app.

1. Install Docker and VS Code with the Dev Containers extension
2. Open the repository in VS Code and select "Reopen in Container"

The container includes Node.js 20, all dependencies, and configured extensions.

Requires Node.js 20 or later:

npm install

• src/app/ - Next.js pages and layouts
• src/components/ - React components with stories and tests
• src/data/ - Mock activity data
• src/services/ - Business logic and data services
• src/utils/ - Utility functions and helpers
• src/schemas/ - Zod validation schemas
• docs/ - Development guides

Sample activities are available at src/data/activities.json for development:

import activities from '@/data/activities.json';

See inline comments in the JSON file for field descriptions.

• Thinking Process & Decisions - Architectural decisions and trade-offs
• Testing Guide - Comprehensive testing principles and best practices
• Storybook Guide - Guidelines for writing effective component stories
• Future Improvements - Planned enhancements and known limitations

Run tests with Vitest:

npm test              # Watch mode
npm run test:run      # CI mode
npm run test:ui       # UI interface
npm run test:coverage # With coverage

See the Testing Guide for detailed guidelines on writing effective tests.

Component documentation and visual testing:

npm run storybook         # Start dev server
npm run build-storybook   # Build static site

See the Storybook Guide for best practices on creating stories.

This project is licensed under the MIT License - see the LICENSE file for details.