eslint-plugin-use-agnostic 0.5.1 → 0.5.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +17 -5
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
`eslint-plugin-use-agnostic` highlights problematic server-client imports in projects made with the Fullstack React Architecture (Next.js App Router, etc.) based on each of their modules' derived effective directives through detailed import rule violations, thanks to the introduction of its very own `'use agnostic'` directive.
|
|
4
4
|
|
|
5
|
-
|
|
6
6
|
|
|
7
7
|
## Installation
|
|
8
8
|
|
|
@@ -55,13 +55,13 @@ And don't forget the VS Code settings via `./.vscode/settings.json`:
|
|
|
55
55
|
|
|
56
56
|
## How it works
|
|
57
57
|
|
|
58
|
-
In the beginning, there were not two kinds of modules in the Fullstack React Architecture (server vs. client)
|
|
58
|
+
In the beginning, there were not two kinds of modules in the Fullstack React Architecture (server vs. client). There were three:
|
|
59
59
|
|
|
60
60
|
- **Server Modules**
|
|
61
61
|
- **Client Modules**
|
|
62
62
|
- and Shared Modules, now **Agnostic Modules**
|
|
63
63
|
|
|
64
|
-
Shared Modules, which I've now renamed
|
|
64
|
+
Shared Modules, which I've now renamed Agnostic Modules, are still here today. In fact, the React team originally anticipated that most modules used in conjunction with React Server Components would be Agnostic Modules. The problem is that Agnostic Modules are never surfaced between the current trifecta of `'use server'`, `'use client'`, and the lack of a directive:
|
|
65
65
|
|
|
66
66
|
- **`'use server'`** denotes modules that exclusively export Server Functions
|
|
67
67
|
- **`'use client'`** denotes modules that exclusively export code that is meant to be executed on the client
|
|
@@ -69,9 +69,9 @@ Shared Modules, which I've now renamed as Agnostic Modules, are still here today
|
|
|
69
69
|
|
|
70
70
|
This means that while `'use server'` denotes some special Server Modules but not all, and `'use client'` denotes all Client Modules regardless of their range of behaviors, the lack of a directive denotes both Server Modules that do possess server-side code, and Agnostic Modules that possess code that is neither server nor client and can safely run in both environments.
|
|
71
71
|
|
|
72
|
-
With the **`'use agnostic'`** directive, taking advantage of its being innocuous and entirely ignored by React at this time, it now becomes possible to manually distinguish between Server Modules, which are to remain unmarked by any directive to fullfill their server-first promise, and Agnostic Modules, which the `'use agnostic'` directive now allows to identify; with `eslint-plugin-use-agnostic` linting your project accordingly.
|
|
72
|
+
With the **`'use agnostic'`** directive, taking advantage of its being innocuous and entirely ignored by React at this time, it now becomes possible to manually distinguish between Server Modules, which are to remain unmarked by any directive in order to fullfill their server-first promise, and Agnostic Modules, which the `'use agnostic'` directive now allows to identify clearly; all with `eslint-plugin-use-agnostic` linting your project accordingly.
|
|
73
73
|
|
|
74
|
-
But it doesn't end there. With React Components into the mix, the reality is that not all Server, Client, and Agnostic Modules are born the same. For example, though a Server Module
|
|
74
|
+
But it doesn't end there. With React Components into the mix (especially RSCs), the reality is that not all Server, Client, and Agnostic Modules are born the same. For example, though a Server Module exporting Server Components cannot import client-side logic, it can actually import and compose with Client Components. This is where a new distinction intervenes, one that particularly takes into account the file extensions of the modules at hand to establish a list of 7 known modules in the Fullstack React Architecture:
|
|
75
75
|
|
|
76
76
|
- **Server Logics Modules**, which _DO NOT_ export React Components, and _DO NOT_ use a JSX file extension
|
|
77
77
|
- **Server Components Modules**, which _ONLY_ export React Components (Server Components), and _ONLY_ use a JSX file extension
|
|
@@ -82,3 +82,15 @@ But it doesn't end there. With React Components into the mix, the reality is tha
|
|
|
82
82
|
- **Agnostic Components Modules**, which _ONLY_ export React Components (Agnostic Components), and _ONLY_ use a JSX file extension
|
|
83
83
|
|
|
84
84
|
With this list established, it thus becomes possible to recognize static import violations between these 7 known modules that `eslint-plugin-use-agnostic` can now highlight for you in your code editor and in the CLI.
|
|
85
|
+
|
|
86
|
+
## Caveats
|
|
87
|
+
|
|
88
|
+
Only the first line of code in a file is observed for the presence of a directive. If no top-of-the-file directive is present or recognized, the file is considered to not have a directive, defaulting to being understood as a Server Logics Module if it doesn't use a JSX file extension (`.js`, `.ts`) or as a Server Components Module if it does (`.jsx`, `.tsx`).
|
|
89
|
+
|
|
90
|
+
Aliased import paths are resolved only if your ESLint config file and your `tsconfig.json` file are in the same directory. (At least to my knowledge.)
|
|
91
|
+
|
|
92
|
+
It is up to you to confirm that your Agnostic Modules are indeed agnostic, meaning that they do not have neither server- nor client-side code. `eslint-plugin-use-agnostic`, at least at this time, does not do this verification for you.
|
|
93
|
+
|
|
94
|
+
It is also up to you to ensure, as outlined above, that **you do not mix** exporting React components with exporting other logics within the same module. Separating exporting React components from their own modules ending with a JSX extension, from other logics from modules that don't end with a JSX extension, is crucial for distinguishing between Logics Modules and Components Modules.
|
|
95
|
+
|
|
96
|
+
The import rules are designed to be as permissive as possible, allowing for more obscure use cases as long as they are non-breaking. However, it is still your responsibility as a developer to, within a file, not mix in incompatible ways code that cannot compose.
|