Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
Frontend Contexts
AuthContext (frontend/src/context/AuthContext.tsx)
Wraps Supabase Auth state and exposes it to the entire app.
What it provides
const {
session, user, signIn, signUp, verifySignUpCode, resendSignUpCode, sendSignInCode, verifySignInCode, sendPasswordReset,
verifyPasswordResetCode, updatePassword, signInWithGoogle, signOut,
} = useAuth();
The value is typed as AuthContextValue, exported from AuthContext.tsx.
| Value | Type | Description |
|---|---|---|
session |
Session | null | undefined |
Current Supabase session; undefined until the first getSession() resolves, null if not logged in |
user |
User | null |
session.user shorthand |
signIn(email, password) |
async function | Calls supabase.auth.signInWithPassword() |
signUp(email, password) |
async function | Calls supabase.auth.signUp() to create a password account, for instances that do not email sign-in codes. With Confirm email on it resolves with a user and no session, and the login page asks for the emailed code |
verifySignUpCode(email, code) |
async function | Calls supabase.auth.verifyOtp({ email, token: code, type: 'signup' }); a correct code confirms the address and signs the user in |
resendSignUpCode(email) |
async function | Calls supabase.auth.resend({ type: 'signup', email }) to email a new code |
sendSignInCode(email) |
async function | Calls supabase.auth.signInWithOtp({ email, options: { shouldCreateUser: true } }); emails a 6-digit code that signs the user in, creating the account the first time an address is used |
verifySignInCode(email, code) |
async function | Calls supabase.auth.verifyOtp({ email, token: code, type: 'email' }); a correct code signs the user in, and also confirms an address that signed up with a password and never confirmed it |
sendPasswordReset(email) |
async function | Calls supabase.auth.resetPasswordForEmail(email, { redirectTo: <origin>/settings }); the email carries a recovery code and a link |
verifyPasswordResetCode(email, code) |
async function | Calls supabase.auth.verifyOtp({ email, token: code, type: 'recovery' }); a correct code signs the user in |
updatePassword(password) |
async function | Calls supabase.auth.updateUser({ password }); sets or changes the password, including for an account that only used Google |
signInWithGoogle(idToken, nonce) |
async function | Calls supabase.auth.signInWithIdToken({ provider: 'google', token, nonce }) with the ID token from Google's button and the raw nonce |
signOut() |
async function | Calls supabase.auth.signOut() |
How it works
const [session, setSession] = useState<Session | null | undefined>(undefined); // undefined = still loading
useEffect(() => {
supabase.auth.getSession().then(({ data: { session } }) => setSession(session));
const { data: { subscription } } = supabase.auth.onAuthStateChange((_event, session) => {
setSession(session);
});
return () => subscription.unsubscribe();
}, []);
onAuthStateChange ensures the session updates in real time when the user signs in, signs out, or the token refreshes.
Where to use it
ProtectedRoute- readssessionto decide whether to redirect to/loginLogin.tsx- callssendSignInCode()andverifySignInCode()(the default email sign-in),signIn(),signUp(),verifySignUpCode(),resendSignUpCode(),sendPasswordReset(),verifyPasswordResetCode(),updatePassword()andsignInWithGoogle()features/settings/PasswordSection.tsx- callsupdatePassword()and readsuser.emailfor password managerslayout/index.tsxandlayout/Sidebar.tsx- the shell callssignOut(); the sidebar user menu showsuser.email- Do not use in page/feature components - they should never need auth state directly
AppContext (frontend/src/context/AppContext.tsx)
Provides the global accounts list and shared utilities to all feature pages.
What it provides
const { accounts, setAccounts, loading, showToast, loadAccounts, refreshAll } = useAppContext();
The value is typed as AppContextValue, exported from AppContext.tsx. useAppContext() throws if it is called outside AppProvider, so callers never handle null.
| Value | Type | Description |
|---|---|---|
accounts |
AppAccount[] |
All connected accounts (YouTube, Instagram), normalized via normalizeAccount() |
setAccounts |
Dispatch<SetStateAction<AppAccount[]>> |
Direct setter (used by AccountManager after add/delete) |
loading |
boolean |
True during refreshAll() only |
showToast(message, severity?) |
(message: string, severity?: ToastSeverity) => void |
Shows a Sonner toast. ToastSeverity: 'success' (default), 'error', 'warning', 'info' |
loadAccounts() |
() => Promise<void> |
Fetches GET /api/accounts and updates accounts |
refreshAll() |
() => Promise<void> |
Calls POST /api/accounts/refresh-all, sets loading true during request |
Loading behavior
loadAccounts() is called automatically on mount. It does not set loading = true - it's a background load. Only refreshAll() sets loading = true (pages that offer Refresh all, such as the Overview, show it as a busy state).
Where to use it
All feature pages and layout components use useAppContext():
Sidebar.tsx- generates per-account nav links fromaccountsOverview.tsx- renders the all-accounts dashboardAccountManager.tsx- callsloadAccounts()after add/deleteChannelAnalytics.tsx- finds the account byparams.id- All pages that show toast notifications call
showToast()
Account shape after normalizeAccount()
AppAccount is defined in frontend/src/utils/formatters.ts: the SafeAccount type from shared/types/domain.ts plus fields older saved accounts can carry, with title and thumbnail filled in per platform. An example:
{
id: 'account-id',
platform: 'youtube' | 'instagram',
// YouTube fields:
channelId: '...',
title: '...',
description: '...',
subscriberCount: 12345,
viewCount: 456789,
videoCount: 100,
thumbnail: '...',
// Instagram fields:
igUserId: '...',
username: '...',
followersCount: 5000,
mediaCount: 200,
// Note: accessToken is NEVER present - stripped by safeAccount() on the backend
}
Shared Hooks (frontend/src/hooks/)
Hooks used by more than one feature. Hooks used by a single feature live in that feature folder instead (see docs/guidelines/REACT.md).
| Hook | File | Purpose |
|---|---|---|
useIsMobile() |
use-mobile.ts |
True below the mobile breakpoint |
useCommandPaletteShortcut(setOpen) |
use-command-palette-shortcut.ts |
Ctrl+K / Cmd+K toggle for the command palette |
useSmoothTheme() |
use-smooth-theme.ts |
Theme switch as one cross-fade |
useCloudinaryConfig(reloadKey) |
use-cloudinary-config.ts |
Loads api.getCloudinaryConfig(); returns { config, loading, error, retry } |
useAccountAnalytics(account, fetchAnalytics, label) |
use-account-analytics.ts |
Loads one account's analytics and refreshes it; used by Instagram analytics |
useCloudinaryConfig keeps loading, ready and failed apart (lib/cloudinaryConfigState.ts), so a slow or failed request never reads as a server without Cloudinary. Loading shows no warning; a failed first load sets error to the server's reason, which the Instagram publishing and YouTube uploads pages show with Try again (retry); a failed refetch keeps the config already loaded. The request runs again whenever reloadKey changes: the Instagram publishing page passes accounts.
useAccountAnalytics returns { loading, profile, analytics, refreshing, handleRefresh }. Pass a stable api method (api.getIGAnalytics), never an inline arrow: the load is keyed on the account id and that method, so a background account refresh does not refetch analytics. label names the platform in the toasts (Couldn't load Instagram analytics., Instagram account refreshed). handleRefresh calls api.refreshAccount() and then loads the analytics again.
Context Rules
- Never use
AuthContextin feature pages - they should not care about auth state - Never use
AppContextinAuthContextor vice versa AppProvidermust be insideProtectedRoute(it makes authenticated API calls on mount)- All toast notifications go through
showToast()- never calltoast()from sonner directly in pages - Do not add new global state to
AppContextunless it truly needs to be shared across multiple unrelated pages. Prefer local component state.