facebook / facebook/docusaurus

Refactor package structures to "client" + "server"

Open
#5,910 2 comments 1 reaction 0 assignees View on GitHub
better engineering proposal
Dominant language
TypeScript
Stars
66.2k
Forks
10k
Avg merge
1d 3h
Merged PRs (30d)
52

Description

### Have you read the Contributing Guidelines on issues?

- [X] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#reporting-new-issues).

### Motivation

All packages should have a `client` and a `server` folder. Here's a good model: https://github.com/cmfcmf/docusaurus-search-local/tree/master/src

## What's wrong with the current setup?

Currently, a plugin's server code is at the root of `src/` while most client code is in `src/theme/`. It's hard to tell which file belongs to Node and which is Webpack, which sometimes leads to server code ending up in client. For most packages the only client folder is `theme`; but for `plugin-content-docs`, for example, it also includes `client`.

Moreover, this makes TS transpilation hard. Had we started with a clear client-server biclassification, a lot of the trouble in #5612 can be avoided. We can simply transpile the two folders with different TSConfigs without worrying about one's output overwriting another. As we go on to work on #5612, we can just watch changes in the client folder, because hot-reloading the server code isn't going to update the website anyways.

## What does it take to separate the two folders?

Almost nothing—just move what's currently in `src/` to `src/server/` and what's in `src/theme/` to `src/client/theme/`. We can also use two `tsconfig` files in `src/server/` and `src/client/` with different types (we shouldn't have `@types/node` in client, for example), and different `.eslintconfig`.

### Self-service

- [X] I'd be willing to do some initial work on this proposal myself.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.