---
id: gh-extension-core-infrastructure
name: "extension-core-infrastructure"
url: https://skills.yangsir.net/skill/gh-extension-core-infrastructure
author: caffeinelabs
domain: ai-app-building-integration
tags: ["react", "authentication", "backend-integration", "infrastructure", "ai-app-development"]
install_count: 27400
rating: 4.60 (120 reviews)
github: https://github.com/caffeinelabs/skills/tree/main/skills/extension-core-infrastructure
---

# extension-core-infrastructure

> 此技能为AI应用提供核心基础设施，包括后端连接配置、Internet Identity认证钩子和Actor管理工具，以及React应用入口点。它简化了AI应用的开发启动过程，确保了安全可靠的身份验证和后端通信，使开发者能专注于业务逻辑实现，加速项目交付。

**Stats**: 27,400 installs · 4.6/5 (120 reviews)

## Before / After 对比

### 核心基础设施搭建效率

**Before**:

用户或开发者需要手动配置复杂的后端连接、实现身份认证逻辑，并为React应用搭建基础结构，这通常涉及多个库的集成和调试，耗时且容易出错，导致项目启动缓慢。

**After**:

此技能提供开箱即用的后端连接、Internet Identity认证钩子和React应用入口点，开发者只需简单集成即可快速启动项目，大幅减少了基础设施搭建的时间和精力投入。

| Metric | Before | After | Change |
|---|---|---|---|
| 核心基础设施搭建时长 | 480分钟 | 30分钟 | -94% |

## Readme

# Core Infrastructure
Core infrastructure extension for [Caffeine AI](https://caffeine.ai?utm_source=caffeine-skill&utm_medium=referral).

## Overview

This component provides the foundational infrastructure for all projects: backend connection configuration, Internet Identity authentication hooks, and actor management utilities.

## Requirements
Requries 
```
"@icp-sdk/auth": "^7.1.0"
"@icp-sdk/core": "^5.3.0"
```

## Integration

Core infrastructure is automatically included in every project. No manual integration steps are required.

# Frontend

The core-infrastructure frontend package (`@caffeineai/core-infrastructure`) is automatically included in every project.

## App Entry Point

Wrap the app with `InternetIdentityProvider` and `QueryClientProvider`:

```typescript
import { InternetIdentityProvider } from "@caffeineai/core-infrastructure";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import ReactDOM from "react-dom/client";
import App from "./App";

const queryClient = new QueryClient();

ReactDOM.createRoot(document.getElementById("root")!).render(
  <QueryClientProvider client={queryClient}>
    <InternetIdentityProvider>
      <App />
    </InternetIdentityProvider>
  </QueryClientProvider>,
);
```

## `useInternetIdentity()` — Authentication Hook

Provides identity state, login, and logout for Internet Identity.

### Return Values

| Field | Type | Description |
|---|---|---|
| `identity` | `Identity \| undefined` | The user's identity (available after login or session restore) |
| `login` | `() => void` | Opens the II popup. Fire-and-forget — do not `await`. |
| `clear` | `() => void` | Logs out and clears stored identity. Fire-and-forget. |
| `isAuthenticated` | `boolean` | `true` when user has a valid identity. **Use this for UI gating.** |
| `isInitializing` | `boolean` | `true` while `AuthClient` is loading from IndexedDB |
| `isLoggingIn` | `boolean` | `true` while the II popup is open |
| `isLoginSuccess` | `boolean` | `true` only after interactive login (NOT after page reload restore) |
| `isLoginError` | `boolean` | `true` if login or initialization failed |
| `loginError` | `Error \| undefined` | The error object when `isLoginError` is `true` |

### Auth State Lifecycle

| Scenario | `loginStatus` | `isAuthenticated` |
|---|---|---|
| Page load, no stored session | `"idle"` | `false` |
| Restoring stored session | `"initializing"` | `false` → `true` |
| Stored session restored after reload | `"idle"` | `true` |
| Interactive login in progress | `"logging-in"` | `false` |
| Interactive login just completed | `"success"` | `true` |
| Login popup failed / cancelled | `"loginError"` | `false` |

**IMPORTANT:** `isLoginSuccess` is only `true` after an interactive login via the popup — NOT when a stored identity is restored on page reload. Always use `isAuthenticated` for conditional rendering.

### Usage

Gate authenticated UI on `isAuthenticated`:
```typescript
const { isAuthenticated } = useInternetIdentity();

{isAuthenticated ? <AuthenticatedApp /> : <LoginScreen />}
```

Disable the login button while initializing or logging in:
```typescript
const { login, isInitializing, isLoggingIn } = useInternetIdentity();

<button onClick={() => login()} disabled={isInitializing || isLoggingIn}>
  Sign in
</button>
```

`login()` and `clear()` are fire-and-forget — the hook's state fields (`isLoggingIn`, `isInitializing`) track the async lifecycle. Do not wrap them in local `useState` / `isPending` logic.

## `useActor()` — Backend Actor Hook

Creates and manages a typed backend actor instance. Automatically re-creates the actor when the user's identity changes (login/logout).

```typescript
import { useActor } from "@caffeineai/core-infrastructure";
import { createActor } from "declarations/backend";

function MyComponent() {
  const { actor, isFetching } = useActor(createActor);

  // actor is null while loading, then the typed backend actor
  if (!actor || isFetching) return <Loading />;

  // Call backend methods directly
  const data = await actor.myBackendMethod();
}
```

### Return Values

| Field | Type | Description |
|---|---|---|
| `actor` | `T \| null` | The typed backend actor, or `null` while loading |
| `isFetching` | `boolean` | `true` while the actor is being created |

When the identity changes (login, logout, or session restore), the actor is automatically re-created with the new identity and all dependent queries are invalidated and refetched.


---
*Source: https://skills.yangsir.net/skill/gh-extension-core-infrastructure*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-extension-core-infrastructure/markdown*