|
1 | 1 | # How to migrate from v1.x to v2.x |
2 | 2 |
|
3 | | -## Table of Contents |
4 | | - |
5 | | -- [Breaking changes](#breaking-changes) |
6 | | -- [Step by step](#step-by-step) |
7 | | - * [Settings](#settings) |
8 | | - * [boundaries/types](#boundariestypes) |
9 | | - * [boundaries/alias](#boundariesalias) |
10 | | - * [Rules](#rules) |
11 | | - * [boundaries/allowed-types](#boundariesprefer-recognized-types) |
12 | | - * [boundaries/entry-point](#boundariesentry-point) |
13 | | - * [boundaries/no-external](#boundariesno-external) |
14 | | - * [boundaries/no-import-ignored](#boundariesno-import-ignored) |
15 | | - * [boundaries/no-import-not-recognized-types](#boundariesno-import-not-recognized-types) |
16 | | - * [boundaries/prefer-recognized-types](#boundariesprefer-recognized-types) |
17 | | - |
18 | | -## Breaking changes |
19 | | - |
20 | | -`eslint-plugin-boundaries` v1.x was working only in projects with a certain files and folders structure, and that was completely changed in v2.x, which can be configured to any type of project structure. This forced to modify the plugin configuration format and main rules options format. |
21 | | - |
22 | | -Another important change introduced was the usage of `eslint-module-utils/resolve` module to resolve the paths of the `imports` in v2.x. This change made the plugin very much solid and customizable for any type of project, but it forced to remove the `boundaries/alias` setting that was present in v1.x. |
23 | | - |
24 | | -Then, since v1.x configurations must be updated prior to upgrading to v2.x, the rules were also renamed to provide clearer and more descriptive names. |
25 | | - |
26 | | -- Removed `boundaries/alias` setting. `import/resolver` has to be used instead |
27 | | -- Renamed `allowed-types` rule into `element-types` (now it can be used to allow/disallow). Changed the format of rule options |
28 | | -- Changed the format of `entry-point` rule options (now it support allow/disallow format) |
29 | | -- Renamed `no-external` rule into `external` (now it can be used to allow/disallow). Changed the format of rule options |
30 | | -- Renamed `no-import-ignored` rule into `no-ignored` (the majority of the plugin rules are referred to `import` statements, so it is not necessary to specify it in the rule name) |
31 | | -- Renamed `no-import-not-recognized-types` rule into `no-unknown` |
32 | | -- Renamed `prefer-recognized-types` rule into `no-unknown-files` |
33 | | - |
34 | | -## Step by step |
35 | | - |
36 | | -Here you have a reference of old v1.x settings and rules, and how to migrate them to v2.x formats. |
37 | | - |
38 | | -### Settings |
39 | | - |
40 | | -#### `boundaries/types` |
41 | | - |
42 | | -The plugin is still compatible with this setting, and it transforms it automatically to a valid `boundaries/elements` setting, but you should migrate as soon as possible this configuration to the [new format](../../README.md#global-settings), as this support will be removed in next major versions. |
43 | | - |
44 | | -Given a `boundaries/types` configuration like: |
45 | | - |
46 | | -```jsonc |
47 | | -{ |
48 | | - "settings": { |
49 | | - "boundaries/types": ["helpers", "components", "modules"] |
50 | | - } |
51 | | -} |
52 | | -``` |
53 | | - |
54 | | -The v2.x plugin transforms it automatically to a `boundaries/elements` configuration like: |
55 | | - |
56 | | -```jsonc |
57 | | -{ |
58 | | - "settings": { |
59 | | - "boundaries/elements": [ |
60 | | - { |
61 | | - "type": "helpers", |
62 | | - "pattern": "helpers/*", |
63 | | - "mode": "folder", |
64 | | - "capture": ["elementName"] |
65 | | - }, |
66 | | - { |
67 | | - "type": "components", |
68 | | - "pattern": "components/*", |
69 | | - "mode": "folder", |
70 | | - "capture": ["elementName"] |
71 | | - }, |
72 | | - { |
73 | | - "type": "modules", |
74 | | - "pattern": "modules/*", |
75 | | - "mode": "folder", |
76 | | - "capture": ["elementName"] |
77 | | - } |
78 | | - ] |
79 | | - } |
80 | | -} |
81 | | -``` |
82 | | - |
83 | | -Take into account that, if you don't migrate this setting by yourself you won't be able to configure elements of type "file", nor use custom `capture` patterns, etc. |
84 | | - |
85 | | -#### `boundaries/alias` |
86 | | - |
87 | | -This setting has been removed in v2.x, and you should use the correspondent [resolver](../../README.md#resolvers) being able to recognize you project aliases. |
88 | | - |
89 | | -For example, if you are using `babel-plugin-module-resolver` in your project to provide aliases, you should install `eslint-import-resolver-babel-module` and configure it in the `import/resolver` setting. Then the plugin will resolve automatically the aliases you have defined for `babel`: |
90 | | - |
91 | | -```jsonc |
92 | | -{ |
93 | | - "settings": { |
94 | | - "import/resolver": { |
95 | | - "babel-module": {} |
96 | | - } |
97 | | - } |
98 | | -} |
99 | | -``` |
100 | | - |
101 | | -Anyway, if you still need to define manually your aliases, you can use the `resolver-legacy-alias` distributed with the v2.x plugin for backward compatibility. So, and old `boundaries/alias` setting like: |
102 | | - |
103 | | -```jsonc |
104 | | -{ |
105 | | - "settings": { |
106 | | - "boundaries/alias": { |
107 | | - "helpers": "src/helpers", |
108 | | - "components": "src/components", |
109 | | - "modules": "src/modules" |
110 | | - } |
111 | | - } |
112 | | -} |
113 | | -``` |
114 | | - |
115 | | -Can be migrated to an `import/resolver` setting like: |
116 | | - |
117 | | -```jsonc |
118 | | -{ |
119 | | - "settings": { |
120 | | - "import/resolver": { |
121 | | - "eslint-import-resolver-node": {}, |
122 | | - "eslint-plugin-boundaries/resolver-legacy-alias": { |
123 | | - "helpers": "./src/helpers", |
124 | | - "components": "./src/components", |
125 | | - "modules": "./src/modules" |
126 | | - } |
127 | | - } |
128 | | - } |
129 | | -} |
130 | | -``` |
131 | | - |
132 | | -### Rules |
133 | | - |
134 | | -#### `boundaries/allowed-types` |
135 | | - |
136 | | -This rule has been renamed into `boundaries/element-types` because now it supports allowing/disallowing based on the rule options. |
137 | | - |
138 | | -Rule options have to be migrated to a [valid v2.x format](../rules/element-types.md). |
139 | | - |
140 | | -Given v1.x options like: |
141 | | - |
142 | | -```jsonc |
143 | | -{ |
144 | | - "rules": { |
145 | | - "boundaries/allowed-types": [2, { |
146 | | - "allow": { |
147 | | - "helpers": [], |
148 | | - "components": ["helpers", "components"], |
149 | | - "modules": ["helpers", "components", "modules"] |
150 | | - } |
151 | | - } |
152 | | - ] |
153 | | - } |
154 | | -} |
155 | | -``` |
156 | | - |
157 | | -Should be migrated to: |
158 | | - |
159 | | -```jsonc |
160 | | -{ |
161 | | - "rules": { |
162 | | - // new rule name |
163 | | - "boundaries/element-types": [2, { |
164 | | - // disallow all, which was the default behavior in v1.x |
165 | | - "default": "disallow", |
166 | | - "rules": [ |
167 | | - // there is no need to migrate "allow.helpers", as they were not allowing anything |
168 | | - // allow importing helpers and components from components |
169 | | - { |
170 | | - "from": ["components"], |
171 | | - "allow": ["helpers", "components"] |
172 | | - }, |
173 | | - // allow importing helpers, components and modules from modules |
174 | | - { |
175 | | - "from": ["modules"], |
176 | | - "allow": ["helpers", "components", "modules"] |
177 | | - } |
178 | | - ] |
179 | | - } |
180 | | - ] |
181 | | - } |
182 | | -} |
183 | | -``` |
184 | | - |
185 | | -#### `boundaries/entry-point` |
186 | | - |
187 | | -Rule options have to be migrated to a [valid v2.x format](../rules/entry-point.md). |
188 | | - |
189 | | -Now configuration presets don't assign a default value to the rule (it was `index.js` in v1.x) |
190 | | - |
191 | | -Given v1.x options like: |
192 | | - |
193 | | -```jsonc |
194 | | -{ |
195 | | - "rules": { |
196 | | - "boundaries/entry-point": [2, { |
197 | | - "default": "main.js", |
198 | | - "byType": { |
199 | | - "components": "Component.js", |
200 | | - "modules": "Module.js" |
201 | | - } |
202 | | - }] |
203 | | - } |
204 | | -} |
205 | | -``` |
206 | | - |
207 | | -Should be migrated to: |
208 | | - |
209 | | -```jsonc |
210 | | -{ |
211 | | - "rules": { |
212 | | - "boundaries/entry-point": [2, { |
213 | | - // disallow all entry-points by default, which was the v1.x behavior |
214 | | - "default": "disallow", |
215 | | - "rules": [ |
216 | | - { |
217 | | - // set default entry point for every elements |
218 | | - "target": ["*"], |
219 | | - "allow": "main.js" |
220 | | - }, |
221 | | - { |
222 | | - // disallow the default one in components and modules |
223 | | - "target": ["components", "modules"], |
224 | | - "disallow": "main.js" |
225 | | - }, |
226 | | - { |
227 | | - // set entry point for components |
228 | | - "target": ["components"], |
229 | | - // allow index.js |
230 | | - "allow": "Component.js" |
231 | | - }, |
232 | | - { |
233 | | - // set entry point for modules |
234 | | - "target": ["modules"], |
235 | | - // only allow index.js |
236 | | - "allow": "Module.js" |
237 | | - } |
238 | | - ] |
239 | | - } |
240 | | - ] |
241 | | - } |
242 | | -} |
243 | | -``` |
244 | | - |
245 | | -> In v2.x format, you should better define a specific entry point for each element. The example shows a workaround that allows to define a default entry point for all elements, and then disallow it in specific elements, which is backward compatible with the v1.x configuration example. This is why the configuration looks more complicated than it should normally be. |
246 | | -
|
247 | | -#### `boundaries/no-external` |
248 | | - |
249 | | -This rule has been renamed into `boundaries/external` because now it supports allowing/disallowing based on the rule options. |
250 | | - |
251 | | -Rule options have to be migrated to a [valid v2.x format](../rules/external.md). |
252 | | - |
253 | | -Given v1.x options like: |
254 | | - |
255 | | -```jsonc |
256 | | -{ |
257 | | - "rules": { |
258 | | - "boundaries/no-external": [2, { |
259 | | - "forbid": { |
260 | | - "helpers": ["react"], |
261 | | - "components": ["react-router-dom"], |
262 | | - "modules": [ |
263 | | - "material-ui", |
264 | | - { |
265 | | - "react-router-dom": ["Link"], |
266 | | - } |
267 | | - ] |
268 | | - } |
269 | | - } |
270 | | - ] |
271 | | - } |
272 | | -} |
273 | | -``` |
274 | | - |
275 | | -Should be migrated to: |
276 | | - |
277 | | -```jsonc |
278 | | -{ |
279 | | - "rules": { |
280 | | - "boundaries/entry-point": [2, { |
281 | | - // allow all external imports by default, which was the v1.x behavior |
282 | | - "default": "allow", |
283 | | - "rules": [ |
284 | | - { |
285 | | - // disallow importing `react` from helpers |
286 | | - "from": ["helpers"], |
287 | | - "disallow": ["react"] |
288 | | - }, |
289 | | - { |
290 | | - // disallow importing `react-router-dom` from components |
291 | | - "from": ["components"], |
292 | | - "disallow": ["react-router-dom"] |
293 | | - }, |
294 | | - { |
295 | | - // disallow importing `react-router-dom` `Link` specifier from modules |
296 | | - "from": ["modules"], |
297 | | - "disallow": [["react-router-dom", { "specifiers": ["Link"] }]] |
298 | | - } |
299 | | - ] |
300 | | - } |
301 | | - ] |
302 | | - } |
303 | | -} |
304 | | -``` |
305 | | - |
306 | | -#### `boundaries/no-import-ignored` |
307 | | - |
308 | | -This rule has been renamed into `boundaries/no-ignored` |
309 | | - |
310 | | -#### `boundaries/no-import-not-recognized-types` |
311 | | - |
312 | | -This rule has been renamed into `boundaries/no-unknown` |
313 | | - |
314 | | -#### `boundaries/prefer-recognized-types` |
315 | | - |
316 | | -This rule has been renamed into `boundaries/no-unknown-files` |
| 3 | +> [!WARNING] |
| 4 | +> This documentation has been migrated to the JS Boundaries project website. |
| 5 | +> |
| 6 | +> Please visit the [new migration guide for v1 to v2](https://www.jsboundaries.dev/docs/releases/migration-guides/v1-to-v2/). |
0 commit comments