Before submitting
Area
apps/web
Problem or use case
t3.json already supports iconPath — a workspace-relative path that ProjectFaviconResolver checks before every built-in location (packages/contracts/src/t3ProjectFile.ts). It works today and it is the intended answer to "my project shows the generic folder icon."
Nothing in the app mentions it. A user who wants to fix their project's icon has no way to discover the field short of reading the resolver source or the JSON Schema. #4935 is someone asking exactly this ("Is this a favicon in the folder? I want to replace it, how can i do this?") and getting no in-app answer. The reporter on #2561 raised the same need after it was closed.
The result is that a solved problem reads as unsolved, and the requests keep arriving as "add custom project icons."
Proposed solution
Surface the existing field where the icon is: show the resolved icon in the project actions dialog with the workspace-relative path it came from, and let it be edited. Writing the value persists iconPath into the repository's t3.json.
To be explicit about what this is not: no icon uploads, no asset storage, no syncing, no new contract field. It reads and writes one string that already exists in a file the repo already owns.
That distinction is why I am filing this rather than reopening #2561, which was closed with "supporting arbitrary uploaded icons would add asset persistence, synchronization, and management UI." That objection is sound and this proposal does not incur any of it.
One design question worth settling before any code: t3.json is checked in and shared with everyone who opens the repo, so editing it from a per-user settings surface changes a teammate's icon too. That may be fine — it is the same sharing model as scripts in the same file — but it should be a deliberate choice, and the UI should make it visible that the write is repo-wide rather than personal.
Why this matters
It closes the loop on the most common icon complaint at close to zero cost, and it reduces the stream of custom-icon requests without building the feature that was already rejected.
Smallest useful scope
Read-only first: display the resolved icon path in the project actions dialog. That alone makes iconPath discoverable, and editing can follow if it proves wanted.
Alternatives considered
Documentation only. Cheaper, but it does not help the person staring at a folder glyph in the app, which is where the question gets asked.
Risks or tradeoffs
Writing a checked-in file from a settings panel is the main one — see the design question above. The read-only scope has none.
Examples or references
Contribution
Before submitting
Area
apps/web
Problem or use case
t3.jsonalready supportsiconPath— a workspace-relative path thatProjectFaviconResolverchecks before every built-in location (packages/contracts/src/t3ProjectFile.ts). It works today and it is the intended answer to "my project shows the generic folder icon."Nothing in the app mentions it. A user who wants to fix their project's icon has no way to discover the field short of reading the resolver source or the JSON Schema. #4935 is someone asking exactly this ("Is this a favicon in the folder? I want to replace it, how can i do this?") and getting no in-app answer. The reporter on #2561 raised the same need after it was closed.
The result is that a solved problem reads as unsolved, and the requests keep arriving as "add custom project icons."
Proposed solution
Surface the existing field where the icon is: show the resolved icon in the project actions dialog with the workspace-relative path it came from, and let it be edited. Writing the value persists
iconPathinto the repository'st3.json.To be explicit about what this is not: no icon uploads, no asset storage, no syncing, no new contract field. It reads and writes one string that already exists in a file the repo already owns.
That distinction is why I am filing this rather than reopening #2561, which was closed with "supporting arbitrary uploaded icons would add asset persistence, synchronization, and management UI." That objection is sound and this proposal does not incur any of it.
One design question worth settling before any code:
t3.jsonis checked in and shared with everyone who opens the repo, so editing it from a per-user settings surface changes a teammate's icon too. That may be fine — it is the same sharing model asscriptsin the same file — but it should be a deliberate choice, and the UI should make it visible that the write is repo-wide rather than personal.Why this matters
It closes the loop on the most common icon complaint at close to zero cost, and it reduces the stream of custom-icon requests without building the feature that was already rejected.
Smallest useful scope
Read-only first: display the resolved icon path in the project actions dialog. That alone makes
iconPathdiscoverable, and editing can follow if it proves wanted.Alternatives considered
Documentation only. Cheaper, but it does not help the person staring at a folder glyph in the app, which is where the question gets asked.
Risks or tradeoffs
Writing a checked-in file from a settings panel is the main one — see the design question above. The read-only scope has none.
Examples or references
packages/contracts/src/t3ProjectFile.ts—iconPathschema and descriptionapps/server/src/project/ProjectFaviconResolver.ts—iconPathprecedenceContribution