[RFC] Support for Configurable Island Locations and Glob Patterns
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 35/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- deno, typescript, vite
- Domain
- build-system, tooling
Research direction
Start by reading Fresh’s configuration and island discovery code to see how the current islands/ and (_islands) conventions feed the compiler; the issue does not name specific files or tests. Then trace how generated manifests and client bundles are produced. Done means a documented configuration can discover islands from the proposed glob patterns while leaving matched static components out of client bundles.
Written by the indexing model from the issue text.
Description
Currently, Fresh relies on "magic folders" (islands/ or (_islands)) to identify interactive components. While this works for small projects, it creates a "Thin/Fat" model dilemma for large-scale, domain-driven architectures (common in monorepos).
I am currently building a site with multiple sections/sub-sections. My desired structure is:
auth/
components/
islands/ <-- Hidden from Fresh unless nested in routes
services/
billing/
islands/ <-- Not automatically detected
To make this work currently, I have to either squeeze everything into a routes/sub-section/(_islands) folder (which causes over-bundling and performance hits) or move them to a global islands/ folder (which breaks domain encapsulation).
Suggested Solution
I would like the ability to explicitly define island entry points or search patterns within the fresh.config.ts or deno.json. This would allow the compiler to "find" islands regardless of where they live in the file tree.
Proposed Configuration
export default defineConfig({
plugins: [
fresh({
islands: [
"./islands/**/*.tsx",
"./sections/**/islands/*.tsx",
"./shared/ui/**/*.island.tsx"
],
}),
],
});
Alternative Solutions
- The (_islands) colocation: While helpful, it forces a specific folder name and deep nesting within the routes directory, making the project structure feel "messy" as it grows.
- Manual Manifesting: Manually editing the fresh.gen.ts, which is fragile and gets overwritten on every save.
Current
routes/
billing/
(_islands)/
PaymentForm.tsx <-- Must be here to work
CardIcon.tsx <-- Forced to be an island (Over-bundling!)
services/
billing_page.tsx
Proposed
features/
billing/
PaymentForm.island.tsx <-- Detected by glob
CardIcon.tsx <-- Remains static (Zero JS)
billing.service.ts
billing.contract.ts
Benfits
-
Enabling Domain-Driven Design (DDD)
Large-scale applications are rarely organized by "technical type" (putting all islands in one bucket). Instead, they are organized by "feature" (Auth, Billing, Dashboard). Current Fresh constraints force developers to break encapsulation by moving interactive logic far away from its related services and contracts. Explicit configuration allows the folder structure to follow the business logic, not the framework's limitations. -
Solving the "Fat Island" Performance Bottleneck
Currently, placing a component in an islands/ or (_islands)/ folder is an "all-or-nothing" choice. If a component lives there, it is bundled for the client. -
First-Class Monorepo Support
In a monorepo setup, interactive UI components often live in a shared workspace (e.g., packages/ui). Currently, importing these into Fresh requires complex workarounds because they aren't in the local islands/ directory. Allowing an array of paths makes shared component libraries "just work." -
Reduced "Magic" and Increased Predictability
Relying on specific folder names like (_islands) is "magic" that can be confusing for new developers (especially those coming from Angular or React backgrounds). Moving this to a configuration file makes the application's boundaries explicit and easier to debug. -
Parity with Modern Tooling
Since Fresh 2.0 is moving toward Vite, developers expect the flexibility that Vite provides. Almost every other modern framework (Astro, Vite-plugin-ssr, etc.) allows for custom entry-point discovery. Adding this keeps Fresh competitive with the ergonomics of the 2026 web ecosystem.
- Dominant language
- TypeScript
- Stars
- 13.8k
- Forks
- 757
- Avg merge
- 3m
- Merged PRs (30d)
- 2
Getting set up
This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from freshframework/fresh
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
freshframework/fresh#3920 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 82/100
freshframework/fresh#3833 ·
-
feat
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
freshframework/fresh#3803 · 1 comment ·
-
Difficulty 5/5 Over a week Newbie friendliness 10/100
freshframework/fresh#3918 · 1 comment · 4 reactions ·
-
Tab title doesn't update to <Head> <title> when navigating to a page with another <title>Possibly taken @1AbdullahButt claimed this 7 days ago. Open
Difficulty 3/5 1-2 days Newbie friendliness 57/100
freshframework/fresh#3916 ·
All issues in freshframework/fresh
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
tintinweb/pi-subagents#459 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
danielmiessler/LifeOS#2830 ·
Maintainers usually reply within 6 days
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
area: client enhancement priority: low
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
opensro-dev/opensro#3681 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
Maintainers usually reply within 1 day