You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This project uses [pnpm](mdc:https:/pnpm.io) for package management. Always use `pnpm` for installing, removing, or updating packages.
24
+
25
+
```bash
26
+
# Install dependencies
27
+
pnpm install
28
+
29
+
# Add a new dependency
30
+
pnpm add <package-name>
31
+
```
32
+
33
+
## Scripts
34
+
35
+
- **`pnpm build:dev`**: Creates a development build of the extension in the `dist/` directory.
36
+
- **`pnpm test:run`**: Runs the unit tests using Vitest.
37
+
- **`pnpm test:e2e`**: Runs end-to-end tests using Playwright.
38
+
- **`pnpm lint`**: Lints the codebase with ESLint.
39
+
- **`pnpm format`**: Formats the code with Prettier.
40
+
- **`pnpm storybook`**: Starts the Storybook server for component development.
41
+
42
+
## Directory Structure
43
+
44
+
- **`src/background`**: Contains the code for the extension's background script.
45
+
- **`service/`**: Houses various services that run in the background, like API calls and wallet logic. See [userWallet.ts](mdc:src/background/service/userWallet.ts).
46
+
- **`utils/`**: Utilities for the background script.
47
+
- **`src/ui`**: Contains all UI-related code.
48
+
- **`components/`**: Shared, reusable React components. See [FRWProfile.tsx](mdc:src/ui/components/FRWProfile.tsx).
49
+
- **`hooks/`**: Custom React hooks. See [use-account-hooks.ts](mdc:src/ui/hooks/use-account-hooks.ts).
50
+
- **`views/`**: Components that represent full pages or views within the extension's UI. See [views/Locked/](mdc:src/ui/views/Locked/index.tsx).
51
+
- **`utils/`**: Utility functions and context providers for the UI.
52
+
- **`src/content-script`**: Code for content scripts that run in the context of web pages.
- **Flow Interaction**: The [@onflow/fcl](mdc:https:/github.com/onflow/fcl-js) library is used for all interactions with the Flow blockchain.
66
+
- **State Management**: The application uses a combination of React hooks, and data cache storage using chrome storage.
67
+
- **Firebase**: Used for remote configuration. See [firebaseConfig.ts](mdc:src/background/utils/firebaseConfig.ts).
68
+
- **Internationalization (i18n)**: Text is managed in [messages.json](mdc:src/messages.json) and loaded via `i18n.ts`.
69
+
70
+
## Data Caching
71
+
72
+
The extension uses a custom stale-while-revalidate caching system designed for the browser extension environment. This is necessary because the React application state is destroyed each time the popup closes. For a detailed explanation, see the [Cache Data Model Architecture](mdc:docs/cache-data-model.md) documentation.
73
+
74
+
### Core Concepts
75
+
76
+
- **Two Types of Storage**:
77
+
1. **Session Storage (Cache Data)**: For temporary, refreshable data synced between the background script and the UI.
78
+
2. **Local Storage (User Data)**: For persistent user settings.
79
+
80
+
- **Data Flow**:
81
+
1. The UI requests data using a hook like `useCachedData`.
82
+
2. If the data is stale or missing, a refresh is triggered in the background service worker.
83
+
3. The background worker fetches new data, updates the cache using `setCachedData`, and the UI is automatically updated via storage listeners.
84
+
85
+
- **Key Principle**: Data is **only ever set or modified by the background script**. The UI reads data and requests refreshes.
86
+
87
+
### Key Files
88
+
89
+
- **`docs/cache-data-model.md`**: The primary documentation for this system.
90
+
- **`src/shared/utils/cache-data-keys.ts`**: Defines keys and data types for temporary session data.
91
+
- **`src/shared/utils/user-data-keys.ts`**: Defines keys and data types for persistent user data.
92
+
- **`src/background/utils/data-cache.ts`**: Contains the core logic for the caching mechanism, including `registerRefreshListener` for single items and `registerBatchRefreshListener` for batching multiple requests.
93
+
94
+
### Implementation Pattern
95
+
96
+
To add new data to the cache:
97
+
1. **Define Keys**: Add key generation functions and type definitions in `cache-data-keys.ts` or `user-data-keys.ts`.
98
+
2. **Create Background Loader**: In a background service, use `registerRefreshListener` or `registerBatchRefreshListener` to define how data is fetched.
99
+
3. **Use Frontend Hooks**: Access data in UI components with the `useCachedData` or `useUserData` hooks.
storybookBuildDir: storybook-static # Directory with Storybook and reports
279
+
exitZeroOnChanges: true # Optional: useful for PR checks
280
+
# workingDir: . # Not needed if storybookBuildDir is set correctly
281
+
282
+
- name: Add Job Summary
250
283
if: always()
251
284
run: |
252
-
echo "::notice title=Playwright Report::View the Playwright report for this run at https://${GITHUB_REPOSITORY_OWNER}.github.io/${GITHUB_REPOSITORY#*/}/runs/${GITHUB_RUN_ID}/"
285
+
echo "## 🎭 Playwright Test Results" >> $GITHUB_STEP_SUMMARY
0 commit comments