A React application built with Vite for managing events and scanning participant QR codes.
- Event Management: View list of events.
- Participant Management: View, add, and manage participants for specific events.
- QR Code Scanner: Built-in scanner to verify participants using
@yudiel/react-qr-scanner(Native Barcode Detection API). - Internationalization: Fully localized in English and French.
- Responsive UI: Built with TailwindCSS and DaisyUI.
- Node.js (Latest LTS recommended)
- npm
npm installStart the development server:
npm run devThe application will be available at http://localhost:5173/scan/ (note the /scan basename).
Build for production:
npm run buildFailed to build? Ensure you have the latest dependencies installed. A known warning regarding chunk size may appear but does not block the build.
You can customize the application behavior and branding at build time using environment variables or by creating a .env file.
| Variable | Default | Description |
|---|---|---|
VITE_APP_TITLE |
CiviScan |
Branding: Name of the application (Title & Home screen). |
VITE_APP_COLOR_PRIMARY |
#00577b |
Branding: Primary brand color (Hex format). |
VITE_GRACE_PERIOD |
30 |
Minutes after an event ends during which it remains editable (Grace Period). |
VITE_SHOW_PAST_EVENTS |
false |
Set to true to show past events by default in the list. |
VITE_ENABLE_SHARE_LINK |
false |
Set to true to enable the "Share Configuration" link in Settings. |
VITE_HIDE_POWERED_BY |
false |
Set to true to hide the "Powered by CiviCRM" footer. |
Example: White-Label Build
To build a "GreenEvent" branded version:
VITE_APP_TITLE="GreenEvent" VITE_APP_COLOR_PRIMARY="#009900" npm run buildThis application supports "Write Once, Run Anywhere" configuration. You can inject configuration values directly into index.html without rebuilding the application (perfect for CiviCRM Extensions).
The application looks for a global window.CIVI_CONFIG object. You can inject this script block into the <head> of index.html:
<script>
window.CIVI_CONFIG = {
featureOauth: 'true', // Enable/Disable OAuth
oauthAuthority: 'https://crm.example.org',
oauthClientId: 'my_client_id'
};
</script>When building with Vite (npm run build), the following placeholders in index.html are automatically replaced by your .env variables:
%VITE_FEATURE_OAUTH%%VITE_OAUTH_AUTHORITY%%VITE_OAUTH_CLIENT_ID%
This allows you to either build a static version with baked-in config OR deploy a generic version and inject config dynamically via your server/CMS.
To allow the Magic Link (and OAuth) to work correctly, you must configure AuthX settings in CiviCRM:
- Go to Administer > System Settings > AuthX.
- Enable "JSON Web Token" for "Acceptable credentials (HTTP Header)".
- Why? The app sends the token via the
Authorization: Bearerheader. If this is disabled, CiviCRM will reject valid tokens with a 403 error.
- Why? The app sends the token via the
- Ensure "Optionally load user accounts" is selected for "User account requirements (HTTP Header)".
📚 More Info: AuthX Documentation
To generate a valid token for testing (replace 2 with your Contact ID):
cv ev "echo Civi::service('crypto.jwt')->encode(['exp' => time() + 86400, 'sub' => 'cid:2', 'scope' => 'authx']) . PHP_EOL;"To allow the Magic Link to open directly in the installed App (instead of the browser):
- Android/iOS: Use standard
https://links. Themanifest.webmanifestis configured withscope: "/scan/". - Magic Link Format:
https://your-site.org/scan/?token=YOUR_JWT_TOKEN - If testing cross-domain (e.g. localhost -> prod), append
&url=https://your-site.org.
src/pages: Main views (EventList, ParticipantList, Scanner, etc.)src/components: Reusable UI componentssrc/services: Logic and API servicessrc/locales: Translation files (en, fr)
The application supports White Labeling via environment variables.
- App Name:
VITE_APP_TITLE - Primary Color:
VITE_APP_COLOR_PRIMARY
These variables automatically update:
- The HTML Title
- The PWA Manifest (App Name, Short Name, Theme Color)
- The CSS Primary Color
You do not need to edit src/index.css manually unless you want deeper customization.
This project includes a GitHub Action that automatically generates a production ZIP file.
- Download the latest release/artifact from GitHub.
- Extract the contents.
- Upload the files to your server.
-
Option 1: Same-Origin (Recommended)
- Upload the files into a folder named
/scanat the root of your CiviCRM website. - URL:
https://yoursite.org/scan/ - Advantage: No configuration required.
- Upload the files into a folder named
-
Option 2: Cross-Origin
- Hosting on a different domain (e.g.,
scan.mydomain.com). - Requirement: You must configure CORS on your server or CiviCRM settings to allow requests from your scanner's domain.
- Hosting on a different domain (e.g.,
Note: This build is hardcoded for the
/scan/base path. If you need a different path (e.g.,/checkin/), you must modifyvite.config.jsand rebuild from source.
To build the application with your specific branding via GitHub Actions:
- Go to your GitHub Repository.
- Navigate to Settings > Secrets and variables > Actions.
- Click on the Variables tab (Not Secrets, unless sensitive).
- Add the following Repository variables:
VITE_APP_TITLE: Your App Name (e.g.CiviScan)VITE_APP_COLOR_PRIMARY: Your Color (e.g.#00577b)VITE_FEATURE_OAUTH:false(ortrue)
The release.yml workflow is already configured to automatically use these variables during the build.