eho/expo-gluestack-setup

Expo gluestack Setup

Use this skill to configure official gluestack-ui in an Expo or React Native project. It can run directly for an existing app, or as a specialist step inside a larger scaffold workflow such as expo-scaffold.

The volatile parts are gluestack CLI behavior, provider APIs, NativeWind compatibility, generated component structure, and package-manager side effects. Verify current official docs and tool output before locking command flags, paths, or verification criteria.

Trigger Boundaries

Use this skill only when one of these is true:

• The user explicitly asks to add, configure, set up, install, repair, or verify gluestack-ui in an existing project.
• The user directly names expo-gluestack-setup.
• expo-scaffold or another new-project scaffold workflow invokes it for a gluestack setup handoff.

Do not use this skill merely because a message mentions gluestack, NativeWind, Expo, a startup failure, dark mode, or a previous scaffold report. For explanation, review, or debugging requests, answer normally unless the user asks you to modify the project’s gluestack setup or directly use this skill.

Modes

Standalone Mode

Use standalone mode when the user asks to add, repair, upgrade, or verify gluestack in an existing project.

Before editing, inspect and resolve:

• Project root and app root.
• Package manager and lockfile policy.
• Expo SDK, React Native, NativeWind, Tailwind CSS, and gluestack versions already present.
• Route/layout shape, especially src/app, root app, or a non-router entry file.
• Existing UI component path, provider path, tailwind.config.*, metro.config.*, babel.config.*, global CSS path, and TypeScript aliases.
• Whether NativeWind is already configured. If it is missing, either configure it only when the user asked for full gluestack setup, or stop with a clear prerequisite if the task is gluestack-only.
• Whether the NativeWind CSS path used by Metro contains @tailwind base;, @tailwind components;, and @tailwind utilities;, and whether Tailwind uses static darkMode: "class" when provider mode is "system".

Orchestrated Mode

Use orchestrated mode when another skill has already created or inspected the app and passes setup decisions. Respect the caller's choices unless they conflict with official gluestack requirements.

Expected inputs from the orchestrator:

• App root.
• Package manager.
• Expo SDK and React Native versions.
• NativeWind status and global CSS path.
• NativeWind preflight result: Tailwind directives present, Metro input path matches the real CSS file, static darkMode: "class" when provider mode is "system", and root layout import status if the caller owns layout wiring.
• Route layout: src/app, root app, or other.
• Desired UI component path, normally src/components/ui for SDK 55 src layouts or components/ui for root layouts.
• Desired gluestack major, or permission to use the current stable compatible major.
• Whether starter components are requested.
• Whether layout wiring or route/screen edits are allowed. Default to no in orchestrated mode.

Return the handoff in the required format below. The orchestrator should use that handoff instead of re-deriving provider paths or setup state.

Version Policy

Default to the current stable gluestack major compatible with the selected Expo SDK and NativeWind setup. If the user requests a specific major, use that major only when official docs and package metadata support it for the project.

If the requested or current gluestack major has no matching complete version reference in this skill, do not silently follow stale v3 steps. Check current official docs and then either:

• Ask before using the newly researched path when compatibility, provider API, CLI flow, or verification criteria are not fully established in this skill.
• Fall back to a documented older stable major only when the user approves or the request explicitly targets that major.
• Return a user-action outcome or blocked when the official path cannot be verified without user action.

For gluestack-ui v3, read references/v3.md before preparing CLI commands, wiring provider output, or verifying setup. For other gluestack majors, read the matching version reference if present. If none exists, proceed only after establishing the package set, provider API, CLI support, NativeWind compatibility, and verification criteria from official docs.

Workflow

1. Inspect the project and determine standalone or orchestrated mode.
2. Confirm NativeWind is installed and configured before starting official gluestack setup. If NativeWind must be added and no orchestrator already owns that work, follow current NativeWind docs or stop with a precise prerequisite. For GluestackUIProvider mode="system", treat NativeWind as configured only when the CSS file used by Metro contains all Tailwind directives and Tailwind uses static darkMode: "class".
3. Select the gluestack major and CLI command path. For v3, use CLI-managed init/add as the only official setup path in this skill.
4. Follow the relevant version reference. For v3, use references/v3.md.
5. When the CLI step requires user interactivity, pause with the exact command, working directory, prompt choices, and current diagnostics. Resume only after the user reports completion.
6. After each user-run CLI step, inspect generated provider/config/components and repair gluestack integration points as needed: Tailwind content/theme, Metro NativeWind input path, Babel aliases/plugins required by generated source, TypeScript aliases, and lockfiles.
7. In orchestrated mode, do not edit root layout or route/screen files unless the caller explicitly allowed layout wiring or route edits. Return exact provider and component import details for the orchestrator instead.
8. Verify that the provider and each starter component import resolve from verified CLI-generated output.
9. Return the required handoff. If setup is blocked or user action is required, stop before claiming completion.

Package Installation Policy

• Use Expo CLI for Expo SDK packages, React Native packages, and native modules where Expo has SDK compatibility knowledge, such as react-native-svg and react-native-web.
• Let the gluestack CLI own gluestack JS package additions unless current official CLI docs require a separate package install or post-CLI verification shows a missing direct/peer dependency. Use the selected package manager directly for Tailwind tooling, local CLIs, and ordinary JavaScript dependencies that Expo does not version-map.
• Do not manually list a package's transitive dependencies in the app manifest. Let the package manager install declared dependencies.
• Add explicit packages only when they are direct app/runtime requirements, documented peer dependencies the app must provide, official gluestack setup-doc requirements, workspace imports, or verified undeclared runtime import workarounds.
• Keep dependency installs in the owning app package. In a monorepo, gluestack mobile runtime packages generated or repaired after CLI setup belong in the Expo app package, not only at the workspace root.
• For missing-module failures, diagnose the source before adding packages. If an installed library imports a module that is absent from its published dependency metadata, add the narrow missing package, document the affected library/version in the handoff, and verify with Metro bundling.

Outcomes

Track exactly one outcome:

• cli_initialized: CLI init succeeded and generated the expected provider/config.
• user_init_required: the user must run the exact gluestack-ui init command in an interactive terminal before setup can continue.
• user_add_required: CLI init is verified, but the user must run the exact gluestack-ui add command before starter components can be wired.
• components_added: CLI init and requested component adds succeeded and generated output was verified.
• blocked: official setup is unusable or cannot be verified.

Do not hand-write lookalike primitives, copy manual provider/component source, or report non-CLI output as official gluestack setup. If the CLI cannot complete even after user-run commands, return blocked.

Handoff

Always end with this handoff when used by another skill, and use the same shape for standalone final reports when practical:

## Gluestack Handoff
- Outcome:
- Mode: standalone | orchestrated
- Version:
- Package versions:
- Dependency exceptions:
- Docs/CLI ref:
- Package manager:
- App root:
- NativeWind prerequisite:
- NativeWind preflight:
- Global CSS path:
- Route root:
- UI component path:
- Provider file path:
- Provider import:
- Provider mode:
- Components generated:
- Component exports:
- Generated source paths:
- CLI component management:
- User action required:
- Commands for user:
- Theme/token status:
- Layout wiring touched:
- Route/screen files touched:
- Commands run:
- Files changed:
- Verification:
- Follow-up:

For user_init_required and user_add_required, include the exact command, working directory, package manager, expected prompt choices, package/lockfile state, and what the user should report back. For cli_initialized, state whether starter components are still required. For components_added, include the verified generated component paths and exports. For blocked, include exact attempted or user-run commands, package/lockfile state, visible errors or hang points, and any partial files left behind.

Boundaries

• This skill owns gluestack packages, provider/components, gluestack theme tokens, and gluestack-specific integration repair.
• This skill may touch NativeWind, Tailwind, Metro, Babel, TypeScript aliases, and lockfiles only as needed to make gluestack work.
• In standalone mode, this skill may wire the root layout or a minimal route/screen when that is necessary to verify the requested gluestack setup. In orchestrated mode, it must not edit layout or route/screen files unless the caller explicitly allows those edits.
• This skill does not choose the broader project shape, create a new Expo app, configure EAS, or own full scaffold verification unless the user asks for those tasks directly.
• When called by expo-scaffold, keep final integration decisions with the orchestrator and report enough detail through the handoff for it to wire screens and final verification.

Useful Official Docs

• gluestack-ui install: https://gluestack.io/ui/docs/home/getting-started/installation
• gluestack-ui dark mode: https://gluestack.io/ui/docs/home/theme-configuration/dark-mode
• gluestack-ui theme customization: https://gluestack.io/ui/docs/home/theme-configuration/customizing-theme
• gluestack-ui source: https://github.com/gluestack/gluestack-ui