This guide covers the development workflow for contributing to the Blueprint project.

Blueprint uses Vite as its build tool, providing a fast development experience with hot module replacement (HMR).

After installing dependencies as per the installation guide, start the development server:

npm run dev

This will start the Vite development server at http://localhost:5173.

Blueprint includes several npm scripts to streamline development:

• npm run dev: Start the development server
• npm run build: Build the production version
• npm run preview: Preview the production build locally
• npm run lint: Run ESLint to check for code issues
• npm run format: Run Prettier to format code
• npm run update: Pull the latest changes and install dependencies
• npm run docker-build: Build the Docker image

1. Create a feature branch

   git checkout -b feature/your-feature-name

2. Implement your changes

   • Follow the project's coding standards
   • Ensure components are correctly typed
   • Add proper documentation for new components or features

3. Run linting and formatting

   npm run lint
   npm run format

4. Commit changes using conventional commits

   git commit -m "feat: add new feature"
   git commit -m "fix: resolve issue with component"

5. Push changes and create a pull request

   git push origin feature/your-feature-name

6. Request a code review

1. Create a bug fix branch

   git checkout -b fix/bug-description

2. Implement the fix

   • Ensure the bug is fully addressed
   • Add tests if possible to prevent regression

3. Commit changes

   git commit -m "fix: resolve issue with X"

4. Push changes and create a pull request

Blueprint enforces code style and standards through ESLint and Prettier:

• ESLint: Enforces code quality rules
• Prettier: Enforces consistent code formatting
• TypeScript: All code should be properly typed

These tools are automatically run via Git hooks using Husky before each commit.

Note: Testing framework is TBD

Once implemented, run tests with:

npm run test

1. Create a new component in the appropriate directory:

   • UI components: /src/components/ui
   • Feature components: /src/components/features
   • Common components: /src/components/common

2. Use TypeScript for proper type definitions:

import React from 'react';

interface MyComponentProps {
  title: string;
  description?: string;
}

export const MyComponent: React.FC<MyComponentProps> = ({ title, description }) => {
  return (
    <div>
      <h2>{title}</h2>
      {description && <p>{description}</p>}
    </div>
  );
};

3. Document the component with JSDoc comments:

/**
 * MyComponent displays a title and optional description.
 * 
 * @component
 * @example
 * ```tsx
 * <MyComponent title="Hello World" description="A simple example" />
 * ```
 */

1. Create a new file in /src/api/endpoints for your API endpoint
2. Use TanStack Query for data fetching and mutations
3. Export your hooks for use in components

Example:

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { databases, ID } from '@/config/appwrite';

export const useMyFeature = (id: string) => {
  return useQuery({
    queryKey: ['myFeature', id],
    queryFn: async () => {
      const response = await databases.getDocument('DATABASE_ID', 'COLLECTION_ID', id);
      return response;
    },
  });
};

1. Create a new file in /src/api/stores for your store
2. Use Zustand for state management
3. Export your store for use in components

Example:

import { create } from 'zustand';

interface MyFeatureState {
  value: string;
  setValue: (newValue: string) => void;
}

export const useMyFeatureStore = create<MyFeatureState>((set) => ({
  value: '',
  setValue: (newValue) => set({ value: newValue }),
}));

Use React DevTools to inspect component hierarchies and props.

TanStack Query includes DevTools to inspect query states and cache:

import { ReactQueryDevtools } from '@tanstack/react-query-devtools';

// Add to your App component
<ReactQueryDevtools initialIsOpen={false} />

npm run build

This creates a production build in the dist directory.

Build the Docker image:

npm run docker-build

Run the container:

docker run -p 80:80 blueprint-app

1. Missing environment variables

   • Check that all required environment variables are set in the env.js file

2. API connection issues

   • Verify Appwrite and Meilisearch are running and accessible
   • Check network requests in browser DevTools

3. Build errors

   • Ensure dependencies are installed correctly
   • Check TypeScript errors and fix type issues