Add expo-project-structure skill for greenfield app layout#91
Open
zvadaadam wants to merge 5 commits into
Open
Add expo-project-structure skill for greenfield app layout#91zvadaadam wants to merge 5 commits into
zvadaadam wants to merge 5 commits into
Conversation
New model-invoked skill documenting Expo's recommended folder structure (the SDK 55+ src/ layout, src/app routes-only, feature colocation) for brand-new projects. Framed as greenfield guidance only — it never restructures an existing app. Added to the plugin README skill list. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
kadikraman
reviewed
Jun 30, 2026
kadikraman
left a comment
kadikraman
left a comment
Contributor
There was a problem hiding this comment.
There's quite a lot missing compared to my blog post. This looks more like a recommended folder structure for a web project.
Notable things I definitely suggest adding:
- a
/screensfolder - in/appyou can only place files that are screens so components that belong to the screen need to either be in the same file or float in a random/componentsfolder otherwise - no mention of API routes: call out how to separate server code - only relevant if you're using API routes, but a huge source of confusion
- where to put your styles
- where to put your tests
- where to place platform specific code (as in if you have a different component for ios and android, AI tends to do an inline if/else for it abut using platform specific components is a lot cleaner for bigger changes)
Not in my blog, but something I suggest you add given your expertise: where to put your AI instruction code like project-specific skills, agents.md / claude.md etc.
| @@ -0,0 +1,58 @@ | |||
| --- | |||
| name: expo-project-structure | |||
| description: Folder structure for a new Expo app — the SDK 55+ `src/` layout, Expo Router `app/` for routes, plus `components/`, `features/`, `hooks/`, `lib/`, `constants/`. Use when scaffolding or laying out a greenfield Expo project, or deciding where a file should live in one. Greenfield guidance only — never restructure an existing app to match. | |||
Contributor
There was a problem hiding this comment.
The SDK 55 note is redundant, I believe this is when we changed the default template to use a /src folder, but it is supported on router since forever.
Suggested change
| description: Folder structure for a new Expo app — the SDK 55+ `src/` layout, Expo Router `app/` for routes, plus `components/`, `features/`, `hooks/`, `lib/`, `constants/`. Use when scaffolding or laying out a greenfield Expo project, or deciding where a file should live in one. Greenfield guidance only — never restructure an existing app to match. | |
| description: Folder structure for a new Expo app. Use when scaffolding or laying out a new Expo project using Expo Router, or deciding where a file should live in one. Greenfield guidance only — never restructure an existing app to match. |
|
|
||
| # Expo Project Structure | ||
|
|
||
| A starting skeleton for a **greenfield** Expo app — one with no committed folder structure yet. |
Contributor
There was a problem hiding this comment.
I don't think we should use the word "greenfield" here, I'd stick with "new" throughout (replacing 6 instances in this diff). This is because in our docs we use "greenfield" to mean "an app that was created using Expo or React Native from the start" vs "brownfield" meaning an app that was created using Swift/Kotlin and React Native was added on top (see https://docs.expo.dev/brownfield/overview/ )
Suggested change
| A starting skeleton for a **greenfield** Expo app — one with no committed folder structure yet. | |
| A starting skeleton for a **new** Expo app — one with no committed folder structure yet. |
|
|
||
| `src/app` holds nothing but route files — screens, `_layout` files, and navigation. Everything else (components, hooks, helpers) lives in the sibling directories above. If both `app/` and `src/app/` exist, Expo Router uses `src/app/` only. | ||
|
|
||
| ## Colocate by feature; promote only what's shared |
Contributor
There was a problem hiding this comment.
I've never been a fan of the feature-based colocation personally, but if you feel strongly about it or it's generally better for LLMs, it's okay.
Address @kadikraman's review on PR #91: - Drop "greenfield" (collides with Expo's brownfield term) — use "new" - Remove SDK 55 note from the description - Replace the invented web-style folders (lib/, store/, types/, components/ui|common, feature-based colocation) with the blog's actual model: screens/, server/ + app/api/, platform-specific files, colocated styles and tests, kebab-case filenames - Add a note on where AI instruction files live (AGENTS.md/CLAUDE.md) - Attribute the source blog post Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Kebab-case rule now cites the default create-expo-app template rather than a version number, honoring the review's "don't version-gate" note. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The plugin-version-bump CI requires the Claude, Codex, and Cursor manifests to be bumped above main (1.5.0) whenever a versioned plugin file changes — adding the new skill's SKILL.md triggered it. Also drops "greenfield" from the README entries to match the skill's wording. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an
expo-project-structureskill documenting Expo's recommended folder layout for brand-new (greenfield) projects, and lists it in the plugin README.The skill
src/layout,src/appas routes-only, and feature-based colocation — promote code to shared dirs only once a second feature needs it.Changes
plugins/expo/skills/expo-project-structure/SKILL.mdplugins/expo/README.mdValidated with
claude plugin validate ./plugins/expo(passes).🤖 Generated with Claude Code