Skip to content

Commit 72172d4

Browse files
jonasjabarijonasjabari
committed
adjusted migration guide
1 parent 544c724 commit 72172d4

File tree

1 file changed

+1
-332
lines changed

1 file changed

+1
-332
lines changed

‎docs/migrate-from-2.x-to-3.0.md

Lines changed: 1 addition & 332 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
# Migrating from 2.x to 3.0
2-
31
# Installation & setup changes
42

53
## Core/Vuejs repo and gem split
@@ -10,109 +8,7 @@
108
- in order to have better seperation of concerns, we've moved the reactivity related things to its own repository/gem -> `matestack-ui-vue_js`
119
- `matestack-ui-core` is now meant to be combined with any reactivity framework or none at all
1210

13-
If you've used reactivity features of `matestack-ui-core` 2.x you now have to install `matestack-ui-vue_js` (Ruby Gem & NPM Package) additionally:
14-
15-
`Gemfile`
16-
```ruby
17-
gem 'matestack-ui-core', '~> 3.0'
18-
gem 'matestack-ui-vue_js', '~> 3.0'
19-
```
20-
21-
**only for `matestack-ui-vue_js` users!**
22-
23-
`package.json`
24-
```json
25-
{
26-
"name": "my-app",
27-
"dependencies": {
28-
"matestack-ui-vue_js": "^3.0.0", // <-- new package name
29-
"..."
30-
}
31-
}
32-
33-
```
34-
35-
## IE 11 support dropped
36-
37-
**only for `matestack-ui-vue_js` users!**
38-
39-
- vue3 dropped IE 11 support
40-
- when using babel alongside webpacker, please adjust your package.json or .browserslistrc config in order to exclude IE 11 support:
41-
42-
```json
43-
{
44-
"name": "my-app",
45-
"...": { },
46-
"browserslist": [
47-
"defaults",
48-
"not IE 11" // <-- important!
49-
]
50-
}
51-
```
52-
53-
Otherwise you may encounter issues around `regeneratorRuntime` (especially when using Vuex)
54-
55-
## Setup via webpacker
56-
57-
**only for `matestack-ui-vue_js` users!**
58-
59-
`config/webpack/environment.js`
60-
```js
61-
const { environment } = require('@rails/webpacker')
62-
const webpack = require('webpack');
63-
64-
const customWebpackConfig = {
65-
resolve: {
66-
alias: {
67-
vue: 'vue/dist/vue.esm-bundler',
68-
}
69-
},
70-
plugins: [
71-
new webpack.DefinePlugin({
72-
__VUE_OPTIONS_API__: true,
73-
__VUE_PROD_DEVTOOLS__: false
74-
})
75-
]
76-
}
77-
78-
environment.config.merge(customWebpackConfig)
79-
80-
module.exports = environment
81-
```
82-
83-
(don't forget to restart webpacker when changing this file!)
84-
85-
and then just use `import { whatever } from 'vue'` instead of `import { whatever } from 'vue/dist/vue.esm'`
86-
87-
**Optional: vue3 compat build usage**
88-
89-
- if you're using any vue2 APIs (or one of the libraries you're using), you can use the vue3 compat build
90-
- this enables you to use both vue2 and vue3 APIs and migrate step by step
91-
- usage via webpack config when using webpacker 5.x and up:
92-
93-
`config/webpack/environment.js`
94-
```js
95-
const { environment } = require('@rails/webpacker')
96-
const webpack = require('webpack')
97-
98-
const customWebpackConfig = {
99-
resolve: {
100-
alias: {
101-
vue: '@vue/compat/dist/vue.esm-bundler',
102-
}
103-
},
104-
plugins: [
105-
new webpack.DefinePlugin({
106-
__VUE_OPTIONS_API__: true,
107-
__VUE_PROD_DEVTOOLS__: false
108-
})
109-
]
110-
}
111-
112-
environment.config.merge(customWebpackConfig)
113-
114-
module.exports = environment
115-
```
11+
**Please follow the migration guide within the docs of `matestack-ui-vuejs` when using reactivity features of `matestack-ui-core` 2.x**
11612

11713
# Ruby related changes
11814

@@ -183,230 +79,3 @@ will just render:
18379
<main>
18480
</body>
18581
```
186-
187-
## `Matestack::Ui::Layout` adjustments when using `matestack-ui-vue_js`
188-
189-
**only for `matestack-ui-vue_js` users!**
190-
191-
- `Matestack::Ui::Layout` classes are no longer automatically wrapped by a component tag meant to mount the matestack-ui-core-app component on it.
192-
- this has to be done manually via the `matestack_vue_js_app` component, which is more explicit and gives more flexibility
193-
- additionally, the `page_switch` component has to wrap the `yield` in order to support dynamic page transitions
194-
195-
`matestack/some/vue_js/app/layout.rb`
196-
```ruby
197-
class Some::VueJs::App::Layout < Matestack::Ui::Layout
198-
199-
def response
200-
h1 "Demo VueJs App"
201-
matestack_vue_js_app do # <-- this one
202-
main do
203-
page_switch do # <-- and this one
204-
yield
205-
end
206-
end
207-
end
208-
end
209-
210-
end
211-
```
212-
213-
- using these components will add the original wrapping DOM structres which enables loading state animations
214-
- new `<matestack-component-tempate>` will be rendered coming from these two new components
215-
216-
```html
217-
<body> <!-- coming from rails layout if specified -->
218-
<div id="matestack-ui"> <!-- coming from rails layout if specified -->
219-
<h1>Demo VueJs App</h1>
220-
<matestack-component-tempate> <!-- new tag rendered since 3.0, should not break anything -->
221-
<div class="matestack-app-wrapper">
222-
<main>
223-
<matestack-component-tempate> <!-- new tag rendered since 3.0, should not break anything -->
224-
<div class="matestack-page-container">
225-
<div class="matestack-page-wrapper">
226-
<div> <!--this div is necessary for conditonal switch to async template via v-if -->
227-
<div class="matestack-page-root">
228-
your page markup
229-
</div>
230-
</div>
231-
</div>
232-
</div>
233-
</matestack-component-tempate>
234-
</main>
235-
</div>
236-
</matestack-component-tempate>
237-
</div>
238-
</body>
239-
```
240-
241-
## `id="matestack-ui"` element can be removed from rails application layout when only using `matestack-ui-core`
242-
243-
**only for `matestack-ui-vue_js` users!**
244-
245-
- if you only use `matestack-ui-core`, you can remove the `id="matestack-ui"` element
246-
- if you use `matestack-ui-vue_js`, this is still required!
247-
248-
`app/views/layouts/application.html.erb`
249-
```html
250-
<body>
251-
<div id="matestack-ui"> <!-- you can remove this div with the matestack-ui ID when not using `matestack-ui-vue_js` -->
252-
<%= yield %>
253-
</div>
254-
</body>
255-
```
256-
257-
# Vuejs related changes in order to support vue3
258-
259-
**only for `matestack-ui-vue_js` users!**
260-
261-
## `MatestackUiCore` is now `MatestackUiVueJs`
262-
263-
- following the repo/gem split, the Vue.js related libary is now called `MatestackUiVueJs`
264-
265-
-> Search&Replace
266-
267-
## app definition and mount
268-
269-
`javascript/packs/application.js`
270-
```js
271-
import { createApp } from 'vue'
272-
import MatestackUiVueJs from 'matestack-ui-vue_js'
273-
274-
const appInstance = createApp({})
275-
276-
document.addEventListener('DOMContentLoaded', () => {
277-
MatestackUiVueJs.mount(appInstance) // use this mount method
278-
})
279-
```
280-
281-
## custom component registration
282-
283-
`some/component/file.js`
284-
```js
285-
import MatestackUiVueJs from 'matestack-ui-vue_js'
286-
287-
const myComponent = {
288-
mixins: [MatestackUiVueJs.componentMixin],
289-
template: MatestackUiVueJs.componentHelpers.inlineTemplate,
290-
data() {
291-
return {
292-
foo: "bar"
293-
};
294-
},
295-
mounted(){
296-
console.log("custom component mounted")
297-
}
298-
};
299-
300-
export default myComponent
301-
```
302-
303-
`javascript/packs/application.js`
304-
```js
305-
import { createApp } from 'vue'
306-
import MatestackUiVueJs from 'matestack-ui-vue_js'
307-
308-
import myComponent from 'some/component/file.js' // import component definition from source
309-
310-
const appInstance = createApp({})
311-
312-
appInstance.component('my-component', myComponent) // register at appInstance
313-
314-
document.addEventListener('DOMContentLoaded', () => {
315-
MatestackUiVueJs.mount(appInstance)
316-
})
317-
```
318-
319-
## component template
320-
321-
- For application components, apply `template: MatestackUiVueJs.componentHelpers.inlineTemplate`
322-
323-
`some/component/file.js`
324-
```js
325-
import MatestackUiVueJs from 'matestack-ui-vue_js'
326-
327-
const myComponent = {
328-
mixins: [MatestackUiVueJs.componentMixin],
329-
template: MatestackUiVueJs.componentHelpers.inlineTemplate, // this one!
330-
data() {
331-
return {
332-
foo: "bar"
333-
};
334-
},
335-
mounted(){
336-
console.log("custom component mounted")
337-
}
338-
};
339-
340-
export default myComponent
341-
```
342-
343-
- Only for core components
344-
- add import `import componentHelpers from 'some/relative/path/to/helpers'`
345-
- and then apply `template: componentHelpers.inlineTemplate`
346-
347-
## component scope prefix
348-
349-
- use `vc.` (short for vue component) in order to prefix all properties references or method calls within your vue.js component `response`
350-
351-
`some/component/file.js`
352-
```js
353-
import MatestackUiVueJs from 'matestack-ui-vue_js'
354-
355-
const myComponent = {
356-
mixins: [MatestackUiVueJs.componentMixin],
357-
template: MatestackUiVueJs.componentHelpers.inlineTemplate,
358-
data() {
359-
return {
360-
foo: "bar"
361-
};
362-
},
363-
mounted(){
364-
console.log(this.foo) // --> bar
365-
// or:
366-
console.log(vc.foo) // --> bar
367-
}
368-
};
369-
370-
export default myComponent
371-
```
372-
373-
```ruby
374-
class Components::MyComponent < Matestack::Ui::VueJsComponent
375-
vue_name "my-component"
376-
377-
def response
378-
div do
379-
plain "{{foo}}" # --> undefined!
380-
plain "{{vc.foo}}" # --> bar
381-
end
382-
end
383-
end
384-
```
385-
386-
## component $refs
387-
388-
- use `this.getRefs()` instead of `this.$refs`
389-
390-
-> Search&Replace
391-
392-
## component $el
393-
394-
- use `this.getElement()` instead of `this.$el`
395-
396-
-> Search&Replace
397-
398-
## component beforeDestroy hook
399-
400-
- `beforeDestroy` was renamed to `beforeUnmount` within vue3
401-
402-
-> Search&Replace
403-
404-
## $set, Vue.set
405-
406-
- `this.$set` and `Vue.set` are removed in vue3 as they are not longer required for proper reactivity binding
407-
- If you use these methods, use plain JavaScript mutations instead
408-
409-
## Vuex store dependency removed
410-
411-
- previously a Vuex store was required and by default available. Now it's optional
412-
- you can add a store manually following the official Vuex 4.x docs

0 commit comments

Comments
 (0)