File layout and colocation

[silviogutierrez]

Reactivated currently splits client files from server files. This is an arbitrary separation and bears discussion.

This separation makes a lot of sense for REST or GraphQL applications where a client consumes resources from a server.

For example, client/App.tsx would be the entry point of a web app. Within this file, a React-side router would dispatch the right section of the app to render.

When a user visits /widgets/, they are still being served client/App.tsx. This then dispatches the client/pages/Widgets.tsx component. So far, the server is uninvolved.

Only when loading this component is an AJAX request dispatched to code in the server. Internally, our app may request /api/widgets/ and render the resources.

The separation is clear.

This is decidedly not the case with Reactivated. When you visit /widgets/, it's a single monolith handling everything.

Think of regular Django without Reactivated. You visit /widgets/. The URL dispatcher maps this to myproject/widgets_app/urls.py. This then loads myproject/widgets_app/views.py which finally renders myproject/widgets_app/templates/widgets.html.

All Reactivated is doing is replacing myproject/widgets_app/templates/widgets.html with a .tsx file. In this case, myproject/widget_app/templates/Widgets.tsx. Why then, should this file live outside in a completely different structure?

Really, all other things being equal, Reactivated could just look for templates inside the app. Note: we use app here in the Django sense. That is, a folder containing related functionality in the same domain.

Django encourages colocation. This is a Good Thing™.

Options

Below are the available options, but feel free to suggest something else.

Note: BASE_DIR is where manage.py, package.json, node_modules, .venv and shell.nix are located. For most repos, this is the root of the repository.

Current convention

- BASE_DIR
  - package.json
  - requirements.txt
  - node_modules
  - client/components/Button.tsx
  - client/templates/PollIndex.tsx
  - client/polls-specific-frontend-logic.tsx
  - client/styles.tsx
  - server/core/utils.py
  - server/polls/models.py
  - server/polls/views.py
  - server/polls/templates.py

Domain or app based approach, but separated by frontend and backend

Again, we use the Django app definition here. We group related functionality, but still separate React and Django.

- BASE_DIR
  - package.json
  - requirements.txt
  - node_modules
  - client/polls/templates/PollIndex.tsx
  - client/polls/specific-frontend-logic.tsx
  - client/core/components/Button.tsx
  - client/core/styles.tsx
  - server/core/utils.py
  - server/core/models.py
  - server/polls/models.py
  - server/polls/views.py
  - server/polls/templates.py

Note the introduction of a core app for both frontend and backend.

This has benefit of grouping things just like Django encourages, but does not mix TypeScript and Python.

Domain or app based approach, co-located

- BASE_DIR
  - package.json
  - requirements.txt
  - node_modules
  - src/polls/templates/PollIndex.tsx
  - src/polls/specific-frontend-logic.tsx
  - src/core/components/Button.tsx
  - src/core/styles.tsx
  - src/core/utils.py
  - src/core/models.py
  - src/polls/models.py
  - src/polls/views.py
  - src/polls/templates.py

Domain or app based approach, co-located with exceptions for components and styles

Very similar to the above, but it feels unnecessary to put components and styles under core.

- BASE_DIR
  - package.json
  - requirements.txt
  - node_modules
  - src/polls/templates/PollIndex.tsx
  - src/polls/specific-frontend-logic.tsx
  - src/components/Button.tsx
  - src/styles.tsx
  - src/core/utils.py
  - src/core/models.py
  - src/polls/models.py
  - src/polls/views.py
  - src/polls/templates.py

More reading

There was this timely article posted on Hacker News: https://www.joshwcomeau.com/react/file-structure/

While I don't agree with a lot of what's said there, the discussion is also a good read: https://news.ycombinator.com/item?id=30684777

Last thoughts

Ultimately, we want to prioritize colocation without upsetting people. But there's real value in wanting to know "where is everything related to polls" and opening BASE_DIR/src/polls and seeing templates, business logic, services, and more.