先决条件

• Node.js LTS
• pnpm (npm install -g pnpm)
• Watchman (macOS/Linux)
• Xcode (iOS) / Android Studio (Android)

安装后步骤

1. 在 VS Code/Cursor 中打开项目并安装推荐的扩展 (ESLint, Prettier, Tailwind CSS IntelliSense)
2. 在 app.config.ts 中更新您的应用名称、包标识符等
3. 在 .env 中配置环境变量
4. 运行 eas init 以设置 EAS Build

文档: https://docs.rn.new/ | GitHub: https://github.com/roninoss/create-expo-stack

技术栈

基于 create-expo-stack (Expo SDK 54)：

项目结构

遵循 references/project-structure.md 中的推荐结构。

├── app/                    # Expo Router 屏幕和布局
├── src/
│   ├── core/               # 核心基础设施 (基础层)
│   │   ├── config/         # 环境变量，常量
│   │   ├── services/       # API 客户端，存储，网络，日志
│   │   │   ├── api/        # HTTP 客户端，拦截器，错误处理器
│   │   │   ├── network/    # NetInfo 监视器，离线队列，同步
│   │   │   └── storage/    # MMKV 包装器
│   │   ├── i18n/           # i18next 配置，RTL 支持
│   │   └── providers/      # 主题，Query，i18n，网络提供者
│   ├── features/           # 功能模块 (自包含)
│   │   └── [feature]/      # screens/, widgets/, api/, hooks/, store/
│   ├── shared/             # 共享组件，钩子，工具
│   │   ├── components/     # ui/, forms/, layout/, feedback/
│   │   └── hooks/          # useDebounce, useMounted 等
│   ├── store/              # 全局状态 (auth, theme, network)
│   └── __tests__/          # 测试设置，模拟，工具
├── assets/                 # 静态资源 (图片，字体)
└── locales/                # i18n JSON 文件 (common, errors, features)

架构层级

app/      → features/, shared/, core/, store/
features/ → shared/, core/, store/ (禁止跨功能模块导入)
shared/   → core/ only
core/     → 无依赖 (基础层)
store/    → core/, shared/

编码规范

详细约定请参考 references/coding-standards.md。

关键规则

1. 文件命名 : 所有文件和文件夹使用 kebab-case (例如 login-form.tsx)
2. 导入 : 使用 @/ 别名进行绝对导入 (使用 --import-alias 配置)
3. 类型导入 : 对于仅类型导入使用 import type
4. 函数限制 : 最多 3 个参数，每个函数最多 70 行
5. 导出 : 优先使用命名导出而非默认导出

组件开发

使用 NativeWind 的 UI 组件

使用带有 NativeWind 的 Tailwind CSS 类。对于复杂的变体，使用 tailwind-variants：

import { tv } from "tailwind-variants";
import { Pressable, Text } from "react-native";

const button = tv({
  base: "rounded-xl px-4 py-3 items-center justify-center",
  variants: {
    variant: {
      primary: "bg-primary-500",
      secondary: "bg-neutral-200 dark:bg-neutral-700",
      destructive: "bg-danger-500",
    },
    disabled: {
      true: "opacity-50",
    },
  },
  defaultVariants: {
    variant: "primary",
  },
});

type ButtonProps = {
  label: string;
  variant?: "primary" | "secondary" | "destructive";
  disabled?: boolean;
  onPress: () => void;
};

export const Button = ({ label, variant, disabled, onPress }: ButtonProps) => (
  <Pressable
    className={button({ variant, disabled })}
    onPress={onPress}
    disabled={disabled}
  >
    <Text className="text-white font-semibold">{label}</Text>
  </Pressable>
);

使用 React Hook Form + Zod 的表单

import { zodResolver } from "@hookform/resolvers/zod";
import { useForm } from "react-hook-form";
import * as z from "zod";

const schema = z.object({
  email: z.string().email("Invalid email"),
  password: z.string().min(6, "Min 6 characters"),
});

type FormData = z.infer<typeof schema>;

export const LoginForm = ({
  onSubmit,
}: {
  onSubmit: (data: FormData) => void;
}) => {
  const { control, handleSubmit } = useForm<FormData>({
    resolver: zodResolver(schema),
  });

  return (
    <View>
      <ControlledInput control={control} name="email" label="Email" />
      <ControlledInput
        control={control}
        name="password"
        label="Password"
        secureTextEntry
      />
      <Button label="Login" onPress={handleSubmit(onSubmit)} />
    </View>
  );
};

状态管理

Zustand 存储模式

import { create } from "zustand";
import { createSelectors } from "@/lib/utils";

interface AuthState {
  token: string | null;
  status: "idle" | "signIn" | "signOut";
  signIn: (token: string) => void;
  signOut: () => void;
}

const _useAuth = create<AuthState>((set) => ({
  token: null,
  status: "idle",
  signIn: (token) => set({ token, status: "signIn" }),
  signOut: () => set({ token: null, status: "signOut" }),
}));

// 使用 createSelectors 进行优化的重新渲染
export const useAuth = createSelectors(_useAuth);

// 导出操作以供在 React 外部使用
export const signIn = (token: string) => _useAuth.getState().signIn(token);
export const signOut = () => _useAuth.getState().signOut();

数据获取

React Query 模式

// api/posts/use-posts.ts
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
import { client } from "../common/client";
import type { Post } from "./types";

export const usePosts = () => {
  return useQuery<Post[]>({
    queryKey: ["posts"],
    queryFn: () => client.get("/posts").then((res) => res.data),
  });
};

export const useCreatePost = () => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data: Omit<Post, "id">) => client.post("/posts", data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["posts"] });
    },
  });
};

导航 (Expo Router)

基于文件的路由

app/
├── _layout.tsx        # 根布局
├── index.tsx          # 主屏幕 (/)
├── login.tsx          # 登录屏幕 (/login)
├── (tabs)/            # 标签页组
│   ├── _layout.tsx    # 标签页布局
│   ├── home.tsx       # /home 标签页
│   └── profile.tsx    # /profile 标签页
└── [id].tsx           # 动态路由 (/:id)

受保护的路由

// app/_layout.tsx
import { useAuth } from "@/lib/auth";
import { Redirect, Stack } from "expo-router";

export default function RootLayout() {
  const status = useAuth.use.status();

  if (status === "signOut") {
    return <Redirect href="/login" />;
  }

  return <Stack />;
}

环境变量

在 env.js 中使用 Zod 进行验证：

const client = z.object({
  APP_ENV: z.enum(["development", "staging", "production"]),
  API_URL: z.string().url(),
  VERSION: z.string(),
});

// 通过 @env 别名访问
import Env from "@env";
console.log(Env.API_URL);

测试

组件测试

import { render, screen, fireEvent } from "@/lib/test-utils";
import { LoginForm } from "./login-form";

describe("LoginForm", () => {
  it("validates email format", async () => {
    const onSubmit = jest.fn();
    render(<LoginForm onSubmit={onSubmit} />);

    fireEvent.changeText(screen.getByTestId("email-input"), "invalid");
    fireEvent.press(screen.getByTestId("login-button"));

    expect(await screen.findByText("Invalid email")).toBeTruthy();
    expect(onSubmit).not.toHaveBeenCalled();
  });
});

快速命令

# 开发
pnpm start                    # 启动 Expo 开发服务器
pnpm ios                      # 在 iOS 模拟器上运行
pnpm android                  # 在 Android 模拟器上运行

# 测试
pnpm test                     # 运行测试
pnpm lint                     # 运行 ESLint
pnpm typecheck               # 运行 TypeScript 检查

# 构建
APP_ENV=staging pnpm build:ios      # 构建 iOS (staging)
APP_ENV=production pnpm build:android  # 构建 Android (production)

资源

架构与模式

• 项目结构 : references/project-structure.md
• 编码规范 : references/coding-standards.md
• 组件模式 : references/component-patterns.md

数据与服务

• 数据层 : references/data-layer.md
• 离线支持 : references/offline.md

国际化与测试

• 国际化指南 : references/i18n.md
• 测试指南 : references/testing.md

每周安装数

1

仓库

allen-hsu/arsenal

首次出现

1 天前

安全审计

Gen Agent Trust HubPassSocketFailSnykPass

安装于

amp1

cline1

opencode1

cursor1

kimi-cli1

codex1

Prerequisites

• Node.js LTS
• pnpm (npm install -g pnpm)
• Watchman (macOS/Linux)
• Xcode (iOS) / Android Studio (Android)

Post-setup

1. Open project in VS Code/Cursor and install recommended extensions (ESLint, Prettier, Tailwind CSS IntelliSense)
2. Update app.config.ts with your app name, bundle ID, etc.
3. Configure environment variables in .env
4. Run eas init to set up EAS Build

Docs: https://docs.rn.new/ | GitHub: https://github.com/roninoss/create-expo-stack

Tech Stack

Based on create-expo-stack (Expo SDK 54):

Project Structure

Follow the recommended structure from references/project-structure.md.

├── app/                    # Expo Router screens and layouts
├── src/
│   ├── core/               # Core infrastructure (base layer)
│   │   ├── config/         # Environment variables, constants
│   │   ├── services/       # API client, storage, network, logger
│   │   │   ├── api/        # HTTP client, interceptors, error handler
│   │   │   ├── network/    # NetInfo monitor, offline queue, sync
│   │   │   └── storage/    # MMKV wrapper
│   │   ├── i18n/           # i18next config, RTL support
│   │   └── providers/      # Theme, Query, i18n, Network providers
│   ├── features/           # Feature modules (self-contained)
│   │   └── [feature]/      # screens/, widgets/, api/, hooks/, store/
│   ├── shared/             # Shared components, hooks, utils
│   │   ├── components/     # ui/, forms/, layout/, feedback/
│   │   └── hooks/          # useDebounce, useMounted, etc.
│   ├── store/              # Global state (auth, theme, network)
│   └── __tests__/          # Test setup, mocks, utilities
├── assets/                 # Static assets (images, fonts)
└── locales/                # i18n JSON files (common, errors, features)

Architecture Layers

app/      → features/, shared/, core/, store/
features/ → shared/, core/, store/ (NO cross-feature imports)
shared/   → core/ only
core/     → No dependencies (base layer)
store/    → core/, shared/

Coding Standards

Refer to references/coding-standards.md for detailed conventions.

Key Rules

1. File naming : Use kebab-case for all files and folders (e.g., login-form.tsx)
2. Imports : Use @/ alias for absolute imports (configure with --import-alias)
3. Type imports : Use import type for type-only imports
4. Function limits : Max 3 parameters, max 70 lines per function
5. Exports : Prefer named exports over default exports

Component Development

UI Components with NativeWind

Use Tailwind CSS classes with NativeWind. For complex variants, use tailwind-variants:

import { tv } from "tailwind-variants";
import { Pressable, Text } from "react-native";

const button = tv({
  base: "rounded-xl px-4 py-3 items-center justify-center",
  variants: {
    variant: {
      primary: "bg-primary-500",
      secondary: "bg-neutral-200 dark:bg-neutral-700",
      destructive: "bg-danger-500",
    },
    disabled: {
      true: "opacity-50",
    },
  },
  defaultVariants: {
    variant: "primary",
  },
});

type ButtonProps = {
  label: string;
  variant?: "primary" | "secondary" | "destructive";
  disabled?: boolean;
  onPress: () => void;
};

export const Button = ({ label, variant, disabled, onPress }: ButtonProps) => (
  <Pressable
    className={button({ variant, disabled })}
    onPress={onPress}
    disabled={disabled}
  >
    <Text className="text-white font-semibold">{label}</Text>
  </Pressable>
);

Forms with React Hook Form + Zod

import { zodResolver } from "@hookform/resolvers/zod";
import { useForm } from "react-hook-form";
import * as z from "zod";

const schema = z.object({
  email: z.string().email("Invalid email"),
  password: z.string().min(6, "Min 6 characters"),
});

type FormData = z.infer<typeof schema>;

export const LoginForm = ({
  onSubmit,
}: {
  onSubmit: (data: FormData) => void;
}) => {
  const { control, handleSubmit } = useForm<FormData>({
    resolver: zodResolver(schema),
  });

  return (
    <View>
      <ControlledInput control={control} name="email" label="Email" />
      <ControlledInput
        control={control}
        name="password"
        label="Password"
        secureTextEntry
      />
      <Button label="Login" onPress={handleSubmit(onSubmit)} />
    </View>
  );
};

State Management

Zustand Store Pattern

import { create } from "zustand";
import { createSelectors } from "@/lib/utils";

interface AuthState {
  token: string | null;
  status: "idle" | "signIn" | "signOut";
  signIn: (token: string) => void;
  signOut: () => void;
}

const _useAuth = create<AuthState>((set) => ({
  token: null,
  status: "idle",
  signIn: (token) => set({ token, status: "signIn" }),
  signOut: () => set({ token: null, status: "signOut" }),
}));

// Use createSelectors for optimized re-renders
export const useAuth = createSelectors(_useAuth);

// Export actions for use outside React
export const signIn = (token: string) => _useAuth.getState().signIn(token);
export const signOut = () => _useAuth.getState().signOut();

Data Fetching

React Query Pattern

// api/posts/use-posts.ts
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
import { client } from "../common/client";
import type { Post } from "./types";

export const usePosts = () => {
  return useQuery<Post[]>({
    queryKey: ["posts"],
    queryFn: () => client.get("/posts").then((res) => res.data),
  });
};

export const useCreatePost = () => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data: Omit<Post, "id">) => client.post("/posts", data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["posts"] });
    },
  });
};

Navigation (Expo Router)

File-based Routing

app/
├── _layout.tsx        # Root layout
├── index.tsx          # Home screen (/)
├── login.tsx          # Login screen (/login)
├── (tabs)/            # Tab group
│   ├── _layout.tsx    # Tab layout
│   ├── home.tsx       # /home tab
│   └── profile.tsx    # /profile tab
└── [id].tsx           # Dynamic route (/:id)

Protected Routes

// app/_layout.tsx
import { useAuth } from "@/lib/auth";
import { Redirect, Stack } from "expo-router";

export default function RootLayout() {
  const status = useAuth.use.status();

  if (status === "signOut") {
    return <Redirect href="/login" />;
  }

  return <Stack />;
}

Environment Variables

Use Zod for validation in env.js:

const client = z.object({
  APP_ENV: z.enum(["development", "staging", "production"]),
  API_URL: z.string().url(),
  VERSION: z.string(),
});

// Access via @env alias
import Env from "@env";
console.log(Env.API_URL);

Testing

Component Testing

import { render, screen, fireEvent } from "@/lib/test-utils";
import { LoginForm } from "./login-form";

describe("LoginForm", () => {
  it("validates email format", async () => {
    const onSubmit = jest.fn();
    render(<LoginForm onSubmit={onSubmit} />);

    fireEvent.changeText(screen.getByTestId("email-input"), "invalid");
    fireEvent.press(screen.getByTestId("login-button"));

    expect(await screen.findByText("Invalid email")).toBeTruthy();
    expect(onSubmit).not.toHaveBeenCalled();
  });
});

Quick Commands

# Development
pnpm start                    # Start Expo dev server
pnpm ios                      # Run on iOS simulator
pnpm android                  # Run on Android emulator

# Testing
pnpm test                     # Run tests
pnpm lint                     # Run ESLint
pnpm typecheck               # Run TypeScript check

# Building
APP_ENV=staging pnpm build:ios      # Build iOS (staging)
APP_ENV=production pnpm build:android  # Build Android (production)

Resources

Architecture & Patterns

• Project Structure : references/project-structure.md
• Coding Standards : references/coding-standards.md
• Component Patterns : references/component-patterns.md

Data & Services

• Data Layer : references/data-layer.md
• Offline Support : references/offline.md

Internationalization & Testing

• i18n Guide : references/i18n.md
• Testing Guide : references/testing.md

Weekly Installs

1

Repository

allen-hsu/arsenal

First Seen

1 day ago

Security Audits

Gen Agent Trust HubPassSocketFailSnykPass

Installed on

amp1

cline1

opencode1

cursor1

kimi-cli1

codex1