@githat/nextjs 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/README.md +510 -0
  2. package/dist/githat.css +334 -0
  3. package/dist/index.d.mts +120 -0
  4. package/dist/index.d.ts +120 -0
  5. package/dist/index.js +663 -0
  6. package/dist/index.js.map +1 -0
  7. package/dist/index.mjs +627 -0
  8. package/dist/index.mjs.map +1 -0
  9. package/dist/middleware.d.mts +10 -0
  10. package/dist/middleware.d.ts +10 -0
  11. package/dist/middleware.js +54 -0
  12. package/dist/middleware.js.map +1 -0
  13. package/dist/middleware.mjs +29 -0
  14. package/dist/middleware.mjs.map +1 -0
  15. package/package.json +50 -0
package/README.md ADDED
@@ -0,0 +1,510 @@
1
+ <div align="center">
2
+
3
+ # @githat/nextjs
4
+
5
+ **Drop-in authentication for Next.js and React apps.**
6
+
7
+ Build secure, multi-tenant applications with pre-built UI components, hooks, and middleware — in under 5 minutes.
8
+
9
+ [![npm version](https://img.shields.io/npm/v/@githat/nextjs)](https://www.npmjs.com/package/@githat/nextjs)
10
+ [![npm downloads](https://img.shields.io/npm/dm/@githat/nextjs)](https://www.npmjs.com/package/@githat/nextjs)
11
+ [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
12
+ [![License](https://img.shields.io/badge/License-Proprietary-red.svg)](./LICENSE)
13
+
14
+ [Quick Start](#quick-start) · [Components](#components) · [Hooks](#hooks) · [Middleware](#middleware) · [Docs](https://githat.io/docs)
15
+
16
+ </div>
17
+
18
+ ---
19
+
20
+ ## Features
21
+
22
+ - **Pre-built UI Components** — Sign-in, sign-up, user button, org switcher — all themed and ready to go
23
+ - **React Hooks** — `useAuth()` and `useGitHat()` for full control over auth state and API calls
24
+ - **Next.js Middleware** — Protect routes at the edge with a single line of config
25
+ - **Multi-Tenant** — Built-in organization switching with role-based access
26
+ - **MCP & Agent Verification** — Verify MCP servers and AI agents on-chain
27
+ - **Dark Theme Included** — Import `@githat/nextjs/styles` for a polished dark UI out of the box
28
+ - **TypeScript First** — Full type definitions for every component, hook, and utility
29
+ - **Dual Output** — Ships ESM + CJS so it works everywhere
30
+
31
+ ---
32
+
33
+ ## Quick Start
34
+
35
+ ### 1. Install
36
+
37
+ ```bash
38
+ npm install @githat/nextjs
39
+ ```
40
+
41
+ ### 2. Get Your Publishable Key
42
+
43
+ Sign up at [githat.io](https://githat.io) and grab your publishable key from the dashboard.
44
+
45
+ ### 3. Wrap Your App with `GitHatProvider`
46
+
47
+ ```tsx
48
+ // app/layout.tsx (Next.js App Router)
49
+ import { GitHatProvider } from '@githat/nextjs';
50
+ import '@githat/nextjs/styles';
51
+
52
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
53
+ return (
54
+ <html lang="en">
55
+ <body>
56
+ <GitHatProvider
57
+ config={{
58
+ publishableKey: process.env.NEXT_PUBLIC_GITHAT_KEY!,
59
+ afterSignInUrl: '/dashboard',
60
+ afterSignOutUrl: '/',
61
+ }}
62
+ >
63
+ {children}
64
+ </GitHatProvider>
65
+ </body>
66
+ </html>
67
+ );
68
+ }
69
+ ```
70
+
71
+ ### 4. Add Sign-In and Sign-Up Pages
72
+
73
+ ```tsx
74
+ // app/sign-in/page.tsx
75
+ import { SignInForm } from '@githat/nextjs';
76
+
77
+ export default function SignInPage() {
78
+ return (
79
+ <div style={{ maxWidth: 400, margin: '80px auto' }}>
80
+ <SignInForm signUpUrl="/sign-up" forgotPasswordUrl="/forgot-password" />
81
+ </div>
82
+ );
83
+ }
84
+ ```
85
+
86
+ ```tsx
87
+ // app/sign-up/page.tsx
88
+ import { SignUpForm } from '@githat/nextjs';
89
+
90
+ export default function SignUpPage() {
91
+ return (
92
+ <div style={{ maxWidth: 400, margin: '80px auto' }}>
93
+ <SignUpForm signInUrl="/sign-in" />
94
+ </div>
95
+ );
96
+ }
97
+ ```
98
+
99
+ ### 5. Protect Routes with Middleware
100
+
101
+ ```ts
102
+ // middleware.ts (project root)
103
+ import { authMiddleware } from '@githat/nextjs/middleware';
104
+
105
+ export default authMiddleware({
106
+ publicRoutes: ['/', '/sign-in', '/sign-up', '/forgot-password'],
107
+ });
108
+
109
+ export const config = {
110
+ matcher: ['/((?!_next|api|.*\\..*).*)'],
111
+ };
112
+ ```
113
+
114
+ ### 6. Use Auth State Anywhere
115
+
116
+ ```tsx
117
+ 'use client';
118
+
119
+ import { useAuth, UserButton, OrgSwitcher } from '@githat/nextjs';
120
+
121
+ export default function DashboardHeader() {
122
+ const { user, org, isSignedIn } = useAuth();
123
+
124
+ if (!isSignedIn) return null;
125
+
126
+ return (
127
+ <header>
128
+ <span>Welcome, {user?.name}</span>
129
+ <OrgSwitcher />
130
+ <UserButton />
131
+ </header>
132
+ );
133
+ }
134
+ ```
135
+
136
+ That's it. You now have a fully authenticated app with sign-in, sign-up, route protection, and org switching.
137
+
138
+ ---
139
+
140
+ ## Components
141
+
142
+ ### Provider
143
+
144
+ | Component | Description | Key Props |
145
+ |------------------|------------------------------------------|---------------------------------------------------------|
146
+ | `GitHatProvider` | Wraps your app and provides auth context | `config` (required) — see [Configuration](#configuration) |
147
+
148
+ ### Authentication Forms
149
+
150
+ | Component | Description | Props |
151
+ |--------------|--------------------------------------|--------------------------------------------------|
152
+ | `SignInForm` | Email + password sign-in form | `onSuccess?`, `signUpUrl?`, `forgotPasswordUrl?` |
153
+ | `SignUpForm` | Name + email + password sign-up form | `onSuccess?`, `signInUrl?` |
154
+
155
+ ### Navigation
156
+
157
+ | Component | Description | Props |
158
+ |----------------|----------------------------------------------|------------------------------------------|
159
+ | `SignInButton` | Link/button to your sign-in page | `className?`, `children?`, `href?` |
160
+ | `SignUpButton` | Link/button to your sign-up page | `className?`, `children?`, `href?` |
161
+ | `UserButton` | Avatar dropdown with user info and sign-out | — (uses context) |
162
+ | `OrgSwitcher` | Dropdown to switch between organizations | — (uses context) |
163
+
164
+ ### Protection & Verification
165
+
166
+ | Component | Description | Props |
167
+ |------------------|--------------------------------------------|--------------------------------------------------------------|
168
+ | `ProtectedRoute` | Redirects unauthenticated users to sign-in | `children`, `fallback?` |
169
+ | `VerifiedBadge` | Displays MCP/agent verification status | `type: 'mcp' \| 'agent'`, `identifier`, `label?` |
170
+
171
+ ### Example: Protected Dashboard
172
+
173
+ ```tsx
174
+ import { ProtectedRoute } from '@githat/nextjs';
175
+
176
+ export default function DashboardPage() {
177
+ return (
178
+ <ProtectedRoute fallback={<p>Checking authentication...</p>}>
179
+ <h1>Dashboard</h1>
180
+ <p>Only authenticated users see this.</p>
181
+ </ProtectedRoute>
182
+ );
183
+ }
184
+ ```
185
+
186
+ ### Example: Verified Badge
187
+
188
+ ```tsx
189
+ import { VerifiedBadge } from '@githat/nextjs';
190
+
191
+ export default function AgentCard() {
192
+ return (
193
+ <div>
194
+ <h3>My MCP Server</h3>
195
+ <VerifiedBadge type="mcp" identifier="tools.example.com" label="Verified" />
196
+ </div>
197
+ );
198
+ }
199
+ ```
200
+
201
+ ---
202
+
203
+ ## Hooks
204
+
205
+ ### `useAuth()`
206
+
207
+ Access the full authentication state and actions. Must be used within a `<GitHatProvider>`.
208
+
209
+ ```tsx
210
+ const {
211
+ // State
212
+ user, // GitHatUser | null
213
+ org, // GitHatOrg | null
214
+ isSignedIn, // boolean
215
+ isLoading, // boolean
216
+ authError, // string | null
217
+
218
+ // Actions
219
+ signIn, // (email: string, password: string) => Promise<void>
220
+ signUp, // (data: SignUpData) => Promise<SignUpResult>
221
+ signOut, // () => Promise<void>
222
+ switchOrg, // (orgId: string) => Promise<void>
223
+ } = useAuth();
224
+ ```
225
+
226
+ #### Example: Custom sign-in flow
227
+
228
+ ```tsx
229
+ 'use client';
230
+
231
+ import { useAuth } from '@githat/nextjs';
232
+ import { useState } from 'react';
233
+
234
+ export function CustomLogin() {
235
+ const { signIn, isLoading, authError } = useAuth();
236
+ const [email, setEmail] = useState('');
237
+ const [password, setPassword] = useState('');
238
+
239
+ const handleSubmit = async (e: React.FormEvent) => {
240
+ e.preventDefault();
241
+ await signIn(email, password);
242
+ // Redirects automatically based on afterSignInUrl config
243
+ };
244
+
245
+ return (
246
+ <form onSubmit={handleSubmit}>
247
+ <input value={email} onChange={e => setEmail(e.target.value)} placeholder="Email" />
248
+ <input value={password} onChange={e => setPassword(e.target.value)} type="password" />
249
+ <button disabled={isLoading}>Sign In</button>
250
+ {authError && <p>{authError}</p>}
251
+ </form>
252
+ );
253
+ }
254
+ ```
255
+
256
+ ### `useGitHat()`
257
+
258
+ Access the GitHat API client for authenticated requests, org management, and verification.
259
+
260
+ ```tsx
261
+ const {
262
+ fetch, // <T>(path: string, init?: RequestInit) => Promise<T>
263
+ getUserOrgs, // () => Promise<{ orgs: GitHatOrg[] }>
264
+ verifyMCP, // (domain: string) => Promise<{ verified: boolean }>
265
+ verifyAgent, // (wallet: string) => Promise<{ verified: boolean }>
266
+ } = useGitHat();
267
+ ```
268
+
269
+ #### Example: Fetching user organizations
270
+
271
+ ```tsx
272
+ 'use client';
273
+
274
+ import { useGitHat } from '@githat/nextjs';
275
+ import { useEffect, useState } from 'react';
276
+ import type { GitHatOrg } from '@githat/nextjs';
277
+
278
+ export function OrgList() {
279
+ const { getUserOrgs } = useGitHat();
280
+ const [orgs, setOrgs] = useState<GitHatOrg[]>([]);
281
+
282
+ useEffect(() => {
283
+ getUserOrgs().then(data => setOrgs(data.orgs));
284
+ }, [getUserOrgs]);
285
+
286
+ return (
287
+ <ul>
288
+ {orgs.map(org => (
289
+ <li key={org.id}>{org.name} ({org.role})</li>
290
+ ))}
291
+ </ul>
292
+ );
293
+ }
294
+ ```
295
+
296
+ #### Example: Calling a custom API endpoint
297
+
298
+ ```tsx
299
+ const { fetch } = useGitHat();
300
+
301
+ // Authenticated request — tokens are attached automatically
302
+ const apps = await fetch<{ apps: App[] }>('/user/apps');
303
+ ```
304
+
305
+ ---
306
+
307
+ ## Middleware
308
+
309
+ The `authMiddleware` function protects your Next.js routes at the edge. Unauthenticated users are redirected to your sign-in page with a `redirect_url` query parameter for post-login redirect.
310
+
311
+ ```ts
312
+ // middleware.ts
313
+ import { authMiddleware } from '@githat/nextjs/middleware';
314
+
315
+ export default authMiddleware({
316
+ publicRoutes: ['/', '/sign-in', '/sign-up', '/pricing'],
317
+ signInUrl: '/sign-in', // default: '/sign-in'
318
+ tokenKey: 'githat_access_token', // default: 'githat_access_token'
319
+ });
320
+
321
+ export const config = {
322
+ matcher: ['/((?!_next|api|.*\\..*).*)'],
323
+ };
324
+ ```
325
+
326
+ ### Middleware Options
327
+
328
+ | Option | Type | Default | Description |
329
+ |----------------|------------|-------------------------|------------------------------------------|
330
+ | `publicRoutes` | `string[]` | `['/']` | Routes accessible without authentication |
331
+ | `signInUrl` | `string` | `'/sign-in'` | Where to redirect unauthenticated users |
332
+ | `tokenKey` | `string` | `'githat_access_token'` | Cookie name to check for the auth token |
333
+
334
+ > **Note:** Since tokens are stored in `localStorage` on the client, middleware performs a cookie presence check. Full token validation happens server-side on API calls. Use the optional cookie bridge pattern to sync `localStorage` tokens to cookies for edge protection.
335
+
336
+ ---
337
+
338
+ ## Configuration
339
+
340
+ ### `GitHatConfig`
341
+
342
+ Pass this to `<GitHatProvider config={...}>`:
343
+
344
+ | Property | Type | Required | Default | Description |
345
+ |-------------------|----------|----------|---------------------------|-----------------------------|
346
+ | `publishableKey` | `string` | Yes | — | Your GitHat publishable key |
347
+ | `apiUrl` | `string` | No | `'https://api.githat.io'` | API base URL |
348
+ | `signInUrl` | `string` | No | `'/sign-in'` | Sign-in page route |
349
+ | `signUpUrl` | `string` | No | `'/sign-up'` | Sign-up page route |
350
+ | `afterSignInUrl` | `string` | No | `'/'` | Redirect after sign-in |
351
+ | `afterSignOutUrl` | `string` | No | `'/'` | Redirect after sign-out |
352
+
353
+ ### Environment Variables
354
+
355
+ ```env
356
+ # .env.local
357
+ NEXT_PUBLIC_GITHAT_KEY=pk_live_xxxxxxxxxxxxx
358
+ ```
359
+
360
+ ### React/Vite Setup
361
+
362
+ The SDK works with any React 18+ app. For Vite or Create React App, wrap your root component the same way:
363
+
364
+ ```tsx
365
+ // main.tsx (Vite)
366
+ import { GitHatProvider } from '@githat/nextjs';
367
+ import '@githat/nextjs/styles';
368
+ import App from './App';
369
+
370
+ ReactDOM.createRoot(document.getElementById('root')!).render(
371
+ <GitHatProvider config={{ publishableKey: import.meta.env.VITE_GITHAT_KEY }}>
372
+ <App />
373
+ </GitHatProvider>
374
+ );
375
+ ```
376
+
377
+ > **Note:** The middleware export (`@githat/nextjs/middleware`) is Next.js-specific. For Vite/CRA apps, use `<ProtectedRoute>` for client-side route protection.
378
+
379
+ ---
380
+
381
+ ## Styling
382
+
383
+ Import the built-in dark theme:
384
+
385
+ ```tsx
386
+ import '@githat/nextjs/styles';
387
+ ```
388
+
389
+ This provides styled defaults for all components (`SignInForm`, `SignUpForm`, `UserButton`, `OrgSwitcher`, etc.). All class names are prefixed with `githat-` to avoid conflicts.
390
+
391
+ ### Customization
392
+
393
+ Override any styles using CSS specificity:
394
+
395
+ ```css
396
+ /* Your global CSS */
397
+ .githat-sign-in-form {
398
+ --githat-primary: #6366f1;
399
+ --githat-bg: #0a0a0a;
400
+ --githat-text: #fafafa;
401
+ border-radius: 12px;
402
+ }
403
+
404
+ .githat-btn-primary {
405
+ background: linear-gradient(135deg, #6366f1, #8b5cf6);
406
+ }
407
+ ```
408
+
409
+ Or skip the built-in styles entirely and style from scratch using the `className` props.
410
+
411
+ ---
412
+
413
+ ## TypeScript
414
+
415
+ Every export is fully typed. Import types directly:
416
+
417
+ ```tsx
418
+ import type {
419
+ GitHatUser,
420
+ GitHatOrg,
421
+ GitHatConfig,
422
+ AuthState,
423
+ AuthActions,
424
+ SignUpData,
425
+ SignUpResult,
426
+ GitHatContextValue,
427
+ } from '@githat/nextjs';
428
+ ```
429
+
430
+ ### Key Types
431
+
432
+ ```ts
433
+ interface GitHatUser {
434
+ id: string;
435
+ email: string;
436
+ name: string;
437
+ avatarUrl: string | null;
438
+ emailVerified: boolean;
439
+ }
440
+
441
+ interface GitHatOrg {
442
+ id: string;
443
+ name: string;
444
+ slug: string;
445
+ role: string;
446
+ tier: string;
447
+ }
448
+
449
+ interface SignUpData {
450
+ email: string;
451
+ password: string;
452
+ name: string;
453
+ acceptMarketing?: boolean;
454
+ }
455
+
456
+ interface SignUpResult {
457
+ requiresVerification: boolean;
458
+ email: string;
459
+ }
460
+ ```
461
+
462
+ ---
463
+
464
+ ## Scaffolding a New Project
465
+
466
+ Use the companion CLI to scaffold a complete Next.js or React app with GitHat auth pre-configured:
467
+
468
+ ```bash
469
+ npx create-githat-app my-app
470
+ ```
471
+
472
+ This generates a full project with sign-in, sign-up, dashboard, settings, and team management pages — all wired up and ready to deploy.
473
+
474
+ ---
475
+
476
+ ## Compatibility
477
+
478
+ | Runtime | Version | Support |
479
+ |------------------------|---------|--------------------|
480
+ | React | >= 18 | Full |
481
+ | Next.js (App Router) | >= 14 | Full |
482
+ | Next.js (Pages Router) | >= 14 | Components + Hooks |
483
+ | Vite + React | >= 5 | Components + Hooks |
484
+ | Create React App | >= 5 | Components + Hooks |
485
+
486
+ ---
487
+
488
+ ## Links
489
+
490
+ - [Documentation](https://githat.io/docs)
491
+ - [Dashboard](https://githat.io/dashboard)
492
+ - [GitHub](https://github.com/GitHat-IO/MicroFrontEnds)
493
+ - [npm](https://www.npmjs.com/package/@githat/nextjs)
494
+ - [CLI: create-githat-app](https://www.npmjs.com/package/create-githat-app)
495
+ - [Report an Issue](https://github.com/GitHat-IO/MicroFrontEnds/issues)
496
+
497
+ ---
498
+
499
+ ## License
500
+
501
+ Proprietary — see [LICENSE](./LICENSE) for details.
502
+
503
+ ---
504
+
505
+ <div align="center">
506
+ <br />
507
+ <strong>Built by <a href="https://githat.io">GitHat</a></strong>
508
+ <br />
509
+ <sub>Identity infrastructure for the agentic web.</sub>
510
+ </div>