[RFC] Toolpad folder layout

[Janpot]

What's the problem? 🤔

Toolpad wants to enable pro-code editing on its data model. Currently the datamodel lives in files inside of a ./toolpad/ folder. We should provide a more ergonomic layout

What are the requirements? ❓

• Easy to navigate
• Allow to copy/move pages between apps

What are our options? 💡

Option 1. Grouping by function

Create top level folders for pages/components/queries.

.
├── components/
│   ├── MyNumber.tsx
│   └── MyChart.tsx
├── pages/
│   ├── page1.yml
│   └── page2.yml
└── queries/
    ├── getUsers.ts
    └── getTickets.ts

Drawbacks:

• Related elements are not colocated. e.g. How easy is to copy a page from one app to the other.
• How do we create hierarchy?

Option 2. Use file extensions to identify objects

.
├── MyNumber.component.tsx
├── MyChart.component.tsx
├── page1.page.yml
├── page2.page.yml
├── page3.page.yml
├── query1.query.ts
└── query2.query.ts

Drawbacks:

• Related elements are not colocated. e.g. How easy is to copy a page from one app to the other.
• How to create hierarchy?

Option 3. Use folders to represent pages

.
├── page1/
│   ├── page.yml
│   └── queries.ts
├── page2/
│   ├── page.yml
│   └── queries.ts
├── page3/
│   ├── page.yml
│   └── queries.ts
├── queries.ts (shared)
└── components/
    ├── MyNumber.tsx
    └── MyChart.tsx

Advantages:

• Easier to create hierarchy
• queries.ts files leave room for the user to organize their queries however they want. e.g. put them all in the same file, or use a barrel file to re-export queries from separate .ts files
• feels a bit like the new Next.js app directory.

Drawbacks:

• All components are shared, how to create a component, for a specific page only? (can't create a components subfolder without it clashing with sub pages)
• Thinking ahead, how do we represent a query created by a visual editor?

Option 4. Use folders + file extensions

.
├── page1/
│   ├── page.yml
│   ├── query1.query.ts
│   ├── query2.query.ts
│   └── MyComponent.component.tsx
├── page2/
│   ├── page.yml
│   ├── query3.query.ts
│   └── MyOtherComponent.component.tsx
├── page3/
│   └── page.yml
├── query4.query.ts
├── MyNumber.component.tsx
└── MyChart.component.tsx

Advantages:

• Easier to create hierarchy
• Thinking ahead: We could think about getUsers.query.yml to represent a query authored by a visual editor

Disadvantages

• Harder to colocate multiple queries/components in 1 file. Less power to the user in terms of organization

Proposed solution 🟢

Options 3. but with a global pages folder

Resources and benchmarks 🔗

No response

[Janpot]

Update from weekly meeting. This is what we'll go with for now:

toolpad
 ┣ .generated
 ┃ ┗ ...
 ┣ components
 ┃ ┣ Component1.tsx
 ┃ ┣ Component2.tsx
 ┃ ┗ Component3.tsx
 ┣ pages
 ┃ ┣ page1
 ┃ ┃ ┗ page.yml
 ┃ ┣ page2
 ┃ ┃ ┗ page.yml
 ┃ ┗ page3
 ┃ ┃ ┗ page.yml
 ┣ resources
 ┃ ┣ my-openapi-spec.yml
 ┃ ┣ my-pg-database.yml
 ┃ ┣ page1-functions.ts
 ┃ ┗ functions2.ts
 ┣ .gitignore
 ┣ app.yml
 ┗ theme.yml

• top level components/pages/resources folders
• we set up pages using folders so that we have an easy path to a folder based file system router that can deeply nest pages
• shared components for the whole app and shared resources for the whole app
• queries.ts will become a resource (functions.ts) and we'll support multiple functions files

[prakhargupta1]

1. In this case, page1-functions.ts is also shared with other pages?
2. Also, when I am editing page-2, I'll see the entire list of resources in the drop-down? And then whichever of these I use, we'll show them in a section like Functions being used in the left panel?

[Janpot]

yes

[prakhargupta1]

Does having a folder for pages allow me to have 2 or more pages in a folder? I mean, if it's a folder it can have more files, so what kind of files it can have? Users will try shifting a function.ts or a component.tsx to this folder to see what happens. So just want to ensure having folder (just for pages) is not a footgun.

[Janpot]

Does having a folder for pages allow me to have 2 or more pages in a folder?

No, you can only have one file named page.yml. Using this layout leaves us the option in the future to nest pages.

I mean, if it's a folder it can have more files, so what kind of files it can have?

Any file, but Toolpad only cares about page.yml (for now)

Users will try shifting a function.ts or a component.tsx to this folder to see what happens.

Users can do many things that we don't specifically prevent. If this really turns out to be a problem we will add a warning. This would fall under the "linter" category of #1851

[prakhargupta1]

I am closing it as we have a decent folder structure now.