Rastapopoulos is a React-based CRUD (Create, Read, Update, Delete) application for managing solar PV install information. It provides a dynamic table interface using Mantine React Table and integrates with the Snowy API for data management.
Rastapopoulos showcases a modular and scalable structure, utilizing various libraries for UI components, state management, and testing. The application allows users to view, create, update, and delete solar PV install information through an intuitive table interface.
- React: A JavaScript library for building user interfaces.
- Next.js: A React framework for applications.
- Mantine: A suite of React components and hooks for building user interfaces.
- Mantine React Table: A powerful and customizable table component for React.
- React Query: A library for managing and synchronizing server state in React applications.
- TypeScript: A typed superset of JavaScript that compiles to plain JavaScript.
- Jest and Testing Library: Tools for writing and running tests for React components.
The project follows a modular and scalable structure, with the following main directories and files:
app/
: Contains the Next.js app structure.elevations/
: Contains the Elevations page and related components. -ElevationTableWrapper.tsx
: A client component that wraps the ElevationTable and handles data fetching and mutations. -page.tsx
: The server component that renders the Elevations page.layout.tsx
: Defines the root layout for the application.page.tsx
: The main page of the application.QueryProvider.tsx
: Provides the React Query client to the application.components/
: Contains reusable UI components for the application.ColorSchemeToggle/
: Allows toggling between light and dark color schemes.ElevationDetails/
: Displays detailed information about a selected elevation.ElevationTable/
: Renders the table for managing elevations.Welcome/
: Displays a welcome message on the main page.hooks/
: Contains custom React hooks.useElevations.ts
: A custom hook for managing elevations data using React Query.services/
: Contains API service functions for interacting with the Snowy API.elevationsService.ts
: Provides functions for fetching, creating, updating, and deleting elevations.types/
: Contains TypeScript type definitions for the application's data models.elevation.ts
: Defines the Elevation interface.utils/
: Contains utility functions and modules.api.ts
: Defines the API request function and API service functions for interacting with the Snowy API.theme.ts
: Defines the Mantine theme configuration for the application.next.config.mjs
: Configuration file for Next.js.postcss.config.cjs
: Configuration file for PostCSS.tsconfig.json
: TypeScript configuration file.jest.config.cjs
andjest.setup.cjs
: Configuration files for Jest testing framework.
- The user navigates to the Elevations page (
app/elevations/page.tsx
). - The
ElevationTableWrapper
component (app/elevations/ElevationTableWrapper.tsx
) fetches the elevations data from the Snowy API using theuseQuery
hook from React Query. - The
ElevationTable
component (components/ElevationTable/ElevationTable.tsx
) renders the table with the fetched elevations data. - The user can perform CRUD operations on the elevations:
- Create: The user can click the "Create New Elevation" button to open a modal and fill in the details for a new elevation. The
createMutation
fromElevationTableWrapper
sends a POST request to the Snowy API to create the new elevation. - Read: The user can view the elevations in the table and click on a row to see more details in the
ElevationDetails
component (components/ElevationDetails/ElevationDetails.tsx
). - Update: The user can click the edit icon on a row to open a modal and update the elevation details. The
updateMutation
fromElevationTableWrapper
sends a PUT request to the Snowy API to update the elevation. - Delete: The user can click the delete icon on a row to delete an elevation. The
deleteMutation
fromElevationTableWrapper
sends a DELETE request to the Snowy API to delete the elevation.
- The
useElevations
hook (hooks/useElevations.ts
) provides the necessary data fetching and mutation functions for managing elevations data using React Query. - The
elevationsService
(services/elevationsService.ts
) acts as an intermediary between the application and the Snowy API, providing functions for fetching, creating, updating, and deleting elevations. - The
api
utility module (utils/api.ts
) handles the API requests and error handling, making use of the Mantine notifications system to display error messages.
- Install dependencies:
npm install
- Start the development server:
npm run dev
- Open the application in your browser at
http://localhost:3000
The project includes several npm scripts for development, testing, building, and deployment. Here's a detailed explanation of each script:
npm run dev
: Starts the Next.js development server. Use this for local development.npm run build
: Creates an optimized production build of the application.npm run analyze
: Builds the application and generates bundle analysis reports.npm run start
: Starts the Next.js production server. Run this afternpm run build
.npm run typecheck
: Runs TypeScript compiler to check for type errors without emitting files.npm run lint
: Runs ESLint and Stylelint to check for code style issues.npm run lint:stylelint
: Runs Stylelint specifically for CSS files.npm run jest
: Runs Jest tests once.npm run jest:watch
: Runs Jest tests in watch mode, re-running tests on file changes.npm run prettier:check
: Checks if all TypeScript and TSX files are formatted correctly.npm run prettier:write
: Automatically formats all TypeScript and TSX files.npm run test
: Runs a full test suite including Prettier checks, linting, type checking, and Jest tests.npm run storybook
: Starts the Storybook development server for component development and testing.npm run storybook:build
: Builds a static Storybook site for deployment.npm run deploy
: Builds and deploys the application to Cloudflare Pages using Wrangler.
The project is configured to deploy to Cloudflare Pages. To deploy the application:
- Ensure you have Wrangler installed globally:
npm install -g wrangler
- Authenticate with Cloudflare:
wrangler login
- Run the deployment script:
npm run deploy
This will build the application and deploy it to:
Note: Make sure you have the necessary permissions and have set up your Cloudflare account correctly before deploying.
The project includes a comprehensive testing setup using Jest and Testing Library. To run the full test suite, use:
npm run test
This command will:
- Check code formatting with Prettier
- Run linting checks with ESLint and Stylelint
- Perform TypeScript type checking
- Execute Jest tests
For development, you can use npm run jest:watch
to run tests in watch mode, which will re-run tests as you make changes to your code.
Storybook is integrated into the project for component development, testing, and documentation. It provides an isolated environment to develop and showcase your React components.
Storybook is already configured in this project. The main configuration files are:
.storybook/main.ts
: Configures Storybook's behavior, addons, and webpack..storybook/preview.tsx
: Sets up the global decorators and parameters for all stories.
To start the Storybook development server, run:
npm run storybook
This will launch Storybook at http://localhost:6006
, allowing you to view and interact with your components in isolation.
To build a static Storybook site for deployment, use:
npm run storybook:build
To create a story for a component:
- Create a new file named
[ComponentName].story.tsx
in the same directory as your component. - Import your component and the necessary Storybook types.
- Define a default export for the component's metadata.
- Export named constants for each story variant.
Example structure for FooterSimple.story.tsx
:
import type { Meta, StoryObj } from '@storybook/react';
import { FooterSimple } from './FooterSimple';
const meta: Meta<typeof FooterSimple> = {
title: 'Components/FooterSimple',
component: FooterSimple,
tags: ['autodocs'],
parameters: {
layout: 'fullscreen',
},
};
export default meta;
type Story = StoryObj<typeof FooterSimple>;
export const Default: Story = {};
export const CustomLinks: Story = {
args: {
links: [
{ link: '#', label: 'About' },
{ link: '#', label: 'Services' },
{ link: '#', label: 'Contact' },
],
},
};
To ensure your components work well with Storybook:
- Use TypeScript for better type inference and documentation.
- Define clear prop interfaces for your components.
- Use default props where appropriate.
- Consider creating multiple story variants to showcase different component states or configurations.
- Keep stories simple and focused on showcasing the component's functionality.
- Use args to make your stories dynamic and interactive.
- Utilize Storybook's addons (like Controls, Actions, and Docs) to enhance your stories.
- Write documentation in your stories using JSDoc comments or the
parameters.docs
field.
If you encounter issues with Storybook:
- Ensure all dependencies are installed (
npm install
). - Check for any errors in the Storybook console or build output.
- Verify that your component imports are correct and all necessary dependencies are available.
- If using custom webpack configurations, ensure they're compatible with Storybook's setup.
By following these guidelines, you can effectively use Storybook to develop, test, and document your React components in isolation, improving the overall development workflow of the project.
The application uses a centralized navigation system defined in utils/navigationItems.ts
. This setup allows for consistent navigation across different components of the application.
The navigation items are defined as an array of objects, each representing a navigation link with the following properties:
link
: The URL or path for the navigation item.label
: The display text for the navigation item.icon
: An icon component from@tabler/icons-react
to be displayed alongside the label.
The centralized navigation items are used in several components:
- HeaderTabs: Displays the main navigation tabs in the header.
- NavbarSimpleColored: Shows the navigation items in the sidebar.
- FooterSimple: Renders navigation links in the footer.
This approach ensures consistency across the application and makes it easier to update the navigation structure globally.
To add, remove, or modify navigation items:
- Open
utils/navigationItems.ts
. - Edit the
navigationItems
array as needed. - The changes will automatically reflect in the HeaderTabs, NavbarSimpleColored, and FooterSimple components.
This centralized approach simplifies navigation management and maintains consistency throughout the application.
To ensure code quality and consistent formatting:
- Run
npm run lint
to check for linting issues. - Use
npm run prettier:check
to verify formatting. - Run
npm run prettier:write
to automatically format your code.
These commands are also part of the npm run test
script, which is recommended to run before committing changes or submitting pull requests.