add documentation

Author: chaoming

content/_index.md

@@ -19,6 +19,58 @@ Our goal is to simplify the complexities of building modern SaaS applications, a
 *   **Modern Development Stack**: Leveraging React, TypeScript, and TailwindCSS for a highly performant, maintainable, and visually appealing frontend.
 *   **Scalable Backend**: Utilizing Firebase (Authentication, Firestore, Cloud Functions) for a serverless, scalable, and cost-effective backend infrastructure.
 
-### Getting Started
+## Learning Path
 
-To begin building your SaaS application with Fireact.dev, follow our comprehensive [Getting Started guide](/getting-started/). It will walk you through the prerequisites, installing the `create-fireact-app` CLI tool, creating a new project, and running your application locally.
+Follow this recommended learning progression from basics to advanced topics:
+
+### 1. Getting Started
+Begin with the [Getting Started guide](/getting-started/) to set up your first Fireact.dev application. This covers:
+- Prerequisites and environment setup
+- Installing `create-fireact-app` CLI
+- Creating and running your first project
+- Understanding the project structure
+
+### 2. Tutorials
+Follow hands-on [Tutorials](/tutorials/) to build real features:
+- [Building Your First Custom Feature](/tutorials/building-first-feature/) - End-to-end feature development
+- [Customizing the UI Theme](/tutorials/customizing-ui-theme/) - Brand your application
+- [Custom Subscription Plans](/tutorials/custom-subscription-plans/) - Advanced billing features
+- [Third-Party Integrations](/tutorials/third-party-integrations/) - Integrate external services
+
+### 3. Examples & Code Snippets
+Explore ready-to-use [Examples](/examples/) for common tasks:
+- Authentication patterns (social login, email verification)
+- Data management (CRUD, real-time updates, pagination)
+- Cloud Functions (triggers, scheduled jobs, error handling)
+- Subscription & billing (payment flows, usage-based billing)
+- UI components (forms, modals, tables)
+- Integration patterns (APIs, webhooks, email)
+
+### 4. Custom Development
+Learn to build advanced custom features in [Custom Development](/custom-development/):
+- Developing custom components and pages
+- Data fetching patterns
+- Localization and internationalization
+- Routing and permission control
+
+### 5. API Reference
+Deep dive into framework internals:
+- [App Package](/app/) - Frontend components, hooks, and utilities
+- [Functions Package](/functions/) - Cloud Functions and backend logic
+
+### 6. Best Practices
+Master production-ready development with [Best Practices](/best-practices/):
+- Code organization and architecture
+- Performance optimization
+- Error handling strategies
+- Testing methodologies
+- Security guidelines
+- Deployment and CI/CD
+
+## Quick Links
+
+- **First time?** Start with [Getting Started](/getting-started/)
+- **Need code?** Check [Examples](/examples/)
+- **Building a feature?** Follow [Tutorials](/tutorials/)
+- **Production ready?** Review [Best Practices](/best-practices/)
+- **Troubleshooting?** See [Troubleshooting Guide](https://github.com/fireact-dev/fireact.dev/blob/main/TROUBLESHOOTING.md)

content/app/_index.md

@@ -3,7 +3,7 @@ title: "@fireact.dev/app Package"
 linkTitle: "App Package"
 type: "docs"
 no_list: true
-weight: 20
+weight: 40
 menu:
   docs:
     parent: "app"

content/best-practices/_index.md

@@ -0,0 +1,215 @@
+---
+title: "Best Practices"
+linkTitle: "Best Practices"
+type: "docs"
+weight: 60
+cascade:
+  type: "docs"
+---
+
+This section covers best practices for building production-ready SaaS applications with Fireact.dev.
+
+## Categories
+
+### Code Organization
+- [Project Structure](code-organization/) - Organize your codebase effectively
+- [Component Design](code-organization/#component-design) - Build maintainable React components
+- [State Management](code-organization/#state-management) - Manage application state
+
+### Performance
+- [Optimization Techniques](performance/) - Improve application performance
+- [Bundle Size Management](performance/#bundle-size) - Reduce JavaScript bundle size
+- [Database Queries](performance/#database-queries) - Optimize Firestore queries
+
+### Security
+- [Security Best Practices](../../SECURITY.md) - Comprehensive security guide (root documentation)
+- [Authentication](security/) - Secure authentication patterns
+- [Authorization](security/#authorization) - Implement proper access control
+- [Data Protection](security/#data-protection) - Protect sensitive data
+
+### Error Handling
+- [Error Handling Guide](error-handling/) - Comprehensive error handling strategies
+- [Client-Side Errors](error-handling/#react-error-handling) - Handle errors in React components
+- [Server-Side Errors](error-handling/#cloud-functions-error-handling) - Handle Cloud Function errors
+- [User Feedback](error-handling/#user-friendly-error-messages) - Communicate errors to users
+
+### Testing
+- [Testing Strategies](testing/) - Comprehensive testing guide
+- [Unit Testing](testing/#react-component-testing) - Test individual components and functions
+- [Integration Testing](testing/#cloud-functions-testing) - Test feature workflows
+- [E2E Testing](testing/#end-to-end-testing) - End-to-end testing strategies
+
+### Deployment
+- [Deployment Guide](../../DEPLOYMENT.md) - Multi-platform deployment guide (root documentation)
+- [CI/CD Setup](../../demo/#cicd) - Automated deployment workflows
+- [Environment Management](../../DEPLOYMENT.md#environment-configuration) - Manage multiple environments
+- [Monitoring](../../DEPLOYMENT.md#monitoring-and-observability) - Monitor production applications
+
+## General Principles
+
+### 1. Follow TypeScript Best Practices
+
+Always use TypeScript for type safety:
+
+```typescript
+// ✅ Good: Explicit types
+interface UserData {
+  name: string;
+  email: string;
+  role: 'admin' | 'user';
+}
+
+const updateUser = async (userId: string, data: UserData): Promise<void> => {
+  // Implementation
+};
+
+// ❌ Bad: Using 'any'
+const updateUser = async (userId: any, data: any): Promise<any> => {
+  // Implementation
+};
+```
+
+### 2. Handle Errors Gracefully
+
+Always handle potential errors:
+
+```typescript
+// ✅ Good: Proper error handling
+try {
+  const result = await functionCall();
+  return result;
+} catch (error) {
+  console.error('Operation failed:', error);
+  throw new Error('User-friendly error message');
+}
+
+// ❌ Bad: No error handling
+const result = await functionCall();
+return result;
+```
+
+### 3. Optimize Performance
+
+Use React best practices for performance:
+
+```typescript
+// ✅ Good: Memoization
+const ExpensiveComponent = React.memo(({ data }) => {
+  const processedData = useMemo(() => {
+    return expensiveCalculation(data);
+  }, [data]);
+
+  return <div>{processedData}</div>;
+});
+
+// ❌ Bad: No optimization
+const ExpensiveComponent = ({ data }) => {
+  const processedData = expensiveCalculation(data); // Runs on every render
+  return <div>{processedData}</div>;
+};
+```
+
+### 4. Secure Your Application
+
+Implement proper security measures:
+
+```typescript
+// ✅ Good: Check permissions
+const deleteSubscription = functions.https.onCall(async (data, context) => {
+  if (!context.auth) {
+    throw new functions.https.HttpsError('unauthenticated', 'Must be logged in');
+  }
+
+  const isOwner = await checkSubscriptionOwnership(
+    context.auth.uid,
+    data.subscriptionId
+  );
+
+  if (!isOwner) {
+    throw new functions.https.HttpsError('permission-denied', 'Not authorized');
+  }
+
+  // Proceed with deletion
+});
+
+// ❌ Bad: No permission checks
+const deleteSubscription = functions.https.onCall(async (data, context) => {
+  await admin.firestore().collection('subscriptions').doc(data.subscriptionId).delete();
+});
+```
+
+### 5. Write Maintainable Code
+
+Keep code clean and maintainable:
+
+```typescript
+// ✅ Good: Small, focused functions with clear names
+const validateEmail = (email: string): boolean => {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return emailRegex.test(email);
+};
+
+const sendWelcomeEmail = async (userEmail: string): Promise<void> => {
+  if (!validateEmail(userEmail)) {
+    throw new Error('Invalid email address');
+  }
+  // Send email logic
+};
+
+// ❌ Bad: Large function doing multiple things
+const processUser = async (data: any) => {
+  // Validation
+  if (!data.email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data.email)) {
+    throw new Error('Invalid email');
+  }
+  // Database operation
+  await db.collection('users').doc(data.id).set(data);
+  // Send email
+  await emailService.send(data.email, 'Welcome!');
+  // Log event
+  console.log('User processed:', data.id);
+};
+```
+
+## Quick Reference Checklist
+
+### Before Deploying
+
+- [ ] All TypeScript errors resolved
+- [ ] Security rules tested and deployed
+- [ ] Environment variables configured
+- [ ] Error handling implemented
+- [ ] Loading states added to UI
+- [ ] Performance optimized
+- [ ] Tests passing
+- [ ] Documentation updated
+
+### Code Quality
+
+- [ ] Consistent naming conventions
+- [ ] Comments for complex logic
+- [ ] No console.logs in production
+- [ ] Proper error messages
+- [ ] TypeScript types defined
+- [ ] Code formatted with ESLint
+
+### Security
+
+- [ ] Authentication required for protected routes
+- [ ] Permissions checked in Cloud Functions
+- [ ] Firestore rules properly configured
+- [ ] Sensitive data not exposed
+- [ ] API keys in environment variables
+- [ ] Input validation implemented
+
+### Performance
+
+- [ ] Images optimized
+- [ ] Code splitting implemented
+- [ ] Database queries optimized
+- [ ] React components memoized where needed
+- [ ] Unnecessary re-renders eliminated
+
+## Contributing
+
+Have best practices to share? See our [Contributing Guide](https://github.com/fireact-dev/fireact.dev/blob/main/CONTRIBUTING.md) to submit your suggestions.