@fireact.dev/core

@fireact.dev/core

Core components and utilities for Fireact applications.

Table of Contents

• Installation
• Project Setup
  • Tailwind CSS Configuration
  • Firebase Configuration
  • Social Login Configuration
  • Internationalization Setup
  • Application Setup
• Testing with Firebase Emulators
• Firebase Deployment
• Components Reference
• License

Installation

npm install @fireact.dev/core

Install the required peer dependencies:

npm install firebase react-router-dom i18next react-i18next @headlessui/react@^1.7.15 @heroicons/react tailwindcss i18next-browser-languagedetector

Note: Make sure to use @headlessui/react version ^1.7.15 as it's a required peer dependency.

Project Setup

Tailwind CSS Configuration

1. Initialize Tailwind:

npx tailwindcss init

1. Update your tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
    "./node_modules/@fireact.dev/core/dist/**/*.{js,mjs}"
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

1. Add Tailwind directives to your src/index.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

Firebase Configuration

Create src/config.json with your Firebase configuration:

{
  "firebase": {
    "apiKey": "your-api-key",
    "authDomain": "your-auth-domain",
    "projectId": "your-project-id",
    "storageBucket": "your-storage-bucket",
    "messagingSenderId": "your-messaging-sender-id",
    "appId": "your-app-id"
  },
  "pages": {
    "home": "/",
    "dashboard": "/dashboard",
    "profile": "/profile",
    "editName": "/edit-name",
    "editEmail": "/edit-email",
    "changePassword": "/change-password",
    "deleteAccount": "/delete-account",
    "signIn": "/signin",
    "signUp": "/signup",
    "resetPassword": "/reset-password"
  },
  "socialLogin": {
    "google": false,
    "microsoft": false,
    "facebook": false,
    "apple": false,
    "github": false,
    "twitter": false,
    "yahoo": false
  },
  "emulators": {
    "enabled": false,
    "host": "localhost",
    "ports": {
      "auth": 9099,
      "firestore": 8080,
      "functions": 5555,
      "hosting": 5002
    }
  }
}

Note: The ConfigProvider will automatically initialize Firebase using this configuration.

Social Login Configuration

To enable social login providers:

1. Set the desired providers to true in the socialLogin section of your config.json
2. Configure each enabled provider in your Firebase Console:
   • Navigate to Authentication > Sign-in method
   • Enable the desired providers
   • Configure OAuth settings
   • Add authorized domains

Internationalization Setup

1. Create the i18n directory structure:

src/
  i18n/
    locales/
      en.ts
      zh.ts

1. Download the base language files from: https://github.com/chaoming/fireact/tree/main/src/i18n/locales

2. Adding or modifying labels: Each language file (e.g., en.ts) follows this structure:

export default {
  email: "Email",
  password: "Password",
  // Add more labels as needed
}

1. Adding a new language:
   1. Create a new file in the locales directory (e.g., fr.ts for French)
   2. Copy the structure from en.ts
   3. Translate all labels to the new language
   4. Add the language to i18n initialization in App.tsx:

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    resources: {
      en: {
        translation: en
      },
      zh: {
        translation: zh
      },
      fr: {
        translation: fr  // Add your new language here
      }
    },
    fallbackLng: 'en',
    interpolation: {
      escapeValue: false
    }
  });

1. Using translations in your components:

import { useTranslation } from 'react-i18next';

function YourComponent() {
  const { t } = useTranslation();

  return (
    <div>
      <h1>{t('common.title')}</h1>
      <p>{t('common.description')}</p>
    </div>
  );
}

Application Setup

1. Create src/main.tsx:

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import './index.css';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

1. Create src/App.tsx:

import { BrowserRouter as Router, Routes, Route, Navigate } from 'react-router-dom';
import {
  AuthProvider,
  ConfigProvider,
  LoadingProvider,
  PublicLayout,
  AuthenticatedLayout,
  SignIn,
  SignUp,
  ResetPassword,
  Dashboard,
  Profile,
  EditName,
  EditEmail,
  ChangePassword,
  DeleteAccount,
  DesktopMenuItems,
  MobileMenuItems,
  Logo
} from '@fireact.dev/core';
import config from './config.json';
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import en from './i18n/locales/en';
import zh from './i18n/locales/zh';

// Initialize i18next
i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    resources: {
      en: {
        translation: en
      },
      zh: {
        translation: zh
      }
    },
    fallbackLng: 'en',
    interpolation: {
      escapeValue: false
    }
  });

function App() {
  return (
    <Router>
      <ConfigProvider config={config}>
        <AuthProvider>
          <LoadingProvider>
            <Routes>
              <Route element={
                <AuthenticatedLayout 
                  desktopMenuItems={<DesktopMenuItems />}
                  mobileMenuItems={<MobileMenuItems />}
                  logo={<Logo className="w-10 h-10" />}
                />
              }>
                <Route path={config.pages.home} element={<Navigate to={config.pages.dashboard} />} />
                <Route path={config.pages.dashboard} element={<Dashboard />} />
                <Route path={config.pages.profile} element={<Profile />} />
                <Route path={config.pages.editName} element={<EditName />} />
                <Route path={config.pages.editEmail} element={<EditEmail />} />
                <Route path={config.pages.changePassword} element={<ChangePassword />} />
                <Route path={config.pages.deleteAccount} element={<DeleteAccount />} />
              </Route>
              <Route element={<PublicLayout logo={<Logo className="w-20 h-20" />} />}>
                <Route path={config.pages.signIn} element={<SignIn />} />
                <Route path={config.pages.signUp} element={<SignUp />} />
                <Route path={config.pages.resetPassword} element={<ResetPassword />} />
              </Route>
            </Routes>
          </LoadingProvider>
        </AuthProvider>
      </ConfigProvider>
    </Router>
  );
}

export default App;

Testing with Firebase Emulators

To use Firebase Emulators for local development and testing:

1. Add emulator settings to your src/config.json:

{
  "emulators": {
    "enabled": true,
    "host": "localhost",
    "ports": {
      "auth": 9099,
      "firestore": 8080,
      "functions": 5555,
      "hosting": 5002
    }
  }
}

1. Configure emulators in firebase.json:

{
  "emulators": {
    "auth": {
      "port": 9099,
      "host": "127.0.0.1"
    },
    "firestore": {
      "port": 8080,
      "host": "127.0.0.1"
    },
    "functions": {
      "port": 5555,
      "host": "127.0.0.1"
    },
    "hosting": {
      "port": 5002,
      "host": "127.0.0.1"
    },
    "ui": {
      "enabled": true,
      "port": 4000,
      "host": "127.0.0.1"
    }
  }
}

1. Start the emulators:

firebase emulators:start

The Emulator UI will be available at http://127.0.0.1:4000

Before deploying to production, disable the emulators by setting enabled to false in your config:

{
  "emulators": {
    "enabled": false
  }
}

Firebase Deployment

1. Install Firebase CLI:

npm install -g firebase-tools

1. Login to Firebase:

firebase login

1. Initialize Firebase in your project:

firebase init

Select the following options:

• Choose "Hosting" when prompted for features
• Select your Firebase project or create a new one
• Set build directory to 'dist' (for Vite projects)
• Configure as a single-page application: Yes
• Don't overwrite index.html

1. Build and deploy:

npm run build
firebase deploy

Your app will be available at:

• https://your-project-id.web.app
• https://your-project-id.firebaseapp.com

Components Reference

Authentication Components

• SignIn - Sign in form
• SignUp - Sign up form
• ResetPassword - Password reset form
• PrivateRoute - Protected route component

User Management Components

• Profile - User profile component
• EditName - Name editing form
• EditEmail - Email editing form
• ChangePassword - Password change form
• DeleteAccount - Account deletion interface
• Avatar - User avatar display

Navigation Components

• DesktopMenuItems - Desktop navigation menu
• MobileMenuItems - Mobile navigation menu
• Logo - Application logo
• LanguageSwitcher - Language selection component

Layout Components

• AuthenticatedLayout - Layout for authenticated pages
• PublicLayout - Layout for public pages
• Message - Message display component
• Dashboard - User dashboard

Context Providers

• AuthContext - Firebase authentication context
• ConfigProvider - Application configuration context
• LoadingContext - Loading state management

Utilities

• userUtils - User-related utility functions

License

MIT