Moving Towards Native Vue
INFO
This article was updated. It previously described the migration as a fixed roadmap tied to specific Shopware versions. Those version-based timelines have been removed because the new systems are still experimental and no release version is committed yet. The article now describes the direction of the migration rather than when each step will happen.
WARNING
The Composition API extension system and the native block system (sw-block) described in this article are experimental. Their APIs can still change, and there is no committed timeline or release version for when they will become the standard.
Introduction
We are planning a significant shift in our development approach, moving towards a more native Vue.js implementation. This document outlines the reasons for this change and provides an overview of the migration path. It serves as a general guideline for our development direction.
Current status
To better understand the changes described in this article, let's recap the current status. The Shopware 6 Administration is built on Vue.js, with several custom systems on top to enable extensions.
Custom component registration
Shopware.Component.register('sw-component', {
template,
//...
});Custom templates with Twig.js
{% block sw-component %}
<sw-card></sw-card>
{% endblock %}Why Go Native?
Our transition to a more native Vue.js approach is driven by several key factors:
Improved Developer Experience
- Devtool enhancements
- Easier maintenance
Future-Proofing
- Aligning with Vue 3 and potential future versions
- Preparing for upcoming industry standards
Performance Optimization
- Leveraging native Vue.js capabilities for better performance
Major Changes
1. Moving from Options API to Composition API
Why Make This Change?
We aim to better align with Vue's ecosystem to minimize the number of specifications new Developers need to learn. The Composition API has become the new standard for Vue documentation and projects across GitHub. Renowned libraries like vue-i18n are dropping support of the Options API, as seen in their migration guide, and we expect similar transitions from other tools in the ecosystem. This also aligns with Vue's best practices, as highlighted in the official Composition API FAQ.
What Will Change?
We will gradually transform our components from Options API to Composition API. Together with native blocks, this lays the foundation for using Single File Components (SFCs). The transformation will happen gradually to give all of us enough time to adapt. Breaking changes, like removing the Options API, will only happen in a future major version. There is no committed timeline or release version for this transition.
Migration Path
The following table shows the current status of both systems and the direction they are heading in:
| System | Status today | Long-term direction |
|---|---|---|
| Options API | Standard | Will be deprecated and removed once the migration to the Composition API is complete |
| Composition API extension system | Experimental | Will become the standard for core components and extensions |
2. TwigJS to Native Blocks
Why Make This Change?
Vue has no native support for blocks like in Twig.js. Vue has slots, but slots don't work like blocks. Recently, we accomplished the unthinkable and found a way to implement blocks with native Vue components. This will allow us to finally use SFC and keep the extendability of Twig.js. Lowering the learning curve, as the Twig.js syntax is especially unfamiliar to Vue developers. Standard tooling like VSCode, ESLint, and Prettier will work out of the box.
What Will Change?
We will gradually transform all component templates from external *.html.twig files with Twig.js into .vue files using the native block implementation.
Migration Path
The following table shows the current status of both systems and the direction they are heading in:
| System | Status today | Long-term direction |
|---|---|---|
| Twig.js blocks | Standard | Will be deprecated and removed once the migration to native blocks is complete |
Native blocks (sw-block) | Experimental | Will become the standard for core components and extensions |
3. Vuex to Pinia
Why Make This Change?
Vuex has been the default State management for Vue 2. For Vue 3, Pinia took its place.
What Will Change?
We will move all core Vuex states to Pinia stores. The public API will change from Shopware.State to Shopware.Store.
Upgrade Path
| Shopware Version | Vuex | Pinia |
|---|---|---|
| 6.7 | Still supported for extensions* | Standard for Core components |
| 6.8 | Removed completely | Standard |
*Extensions still can register Vuex states; Accessing core stores is done via Pinia
Example: Component Evolution
Now let's take a look at how core and extension components will evolve.
Today: The stable extension system
First, we start with the current status: components are registered with the Options API and use Twig.js templates.
Core component
In the core, we register a component via Shopware.Component.register.
Shopware.Component.register('sw-text-field', {
template: `
{% block sw-text-field %}
<input type=text v-model="value" @change="onChange">
{% endblock %}
`,
data() {
return {
value: null,
}
},
methods: {
onChange() {
this.$emit('update:value', this.value);
}
},
});Extension override
The extension overrides the component via Shopware.Component.override.
Shopware.Component.override('sw-text-field', {
template: `
{% block sw-text-field %}
{% parent %}
{{ helpText }}
{% endblock %}
`,
props: {
helpText: {
type: String,
required: false,
}
}
})Extension new component
The extension adds an additional component via Shopware.Component.register.
Shopware.Component.register('your-crazy-ai-field', {
template: `
{% block your-crazy-ai-field %}
{# ... #}
{% endblock %}
`,
// Options API implementation
})Experimental: The native extension system
WARNING
The APIs shown in this example are experimental and can still change.
Once components are migrated, the core will use single-file components with the Composition API. You can already try out this system today as an experimental feature.
Core component
The core component is added via a single-file component *.vue file.
<template>
{# Notice native block component instead of twig blocks #}
<sw-block name="sw-text-field">
<input type=text v-model="value" @change="onChange">
</sw-block>
</template>
<script setup>
// Notice Composition API imports
import { ref, defineEmits } from 'vue';
// Notice the new Shopware extension system.Component.createExtendableSetup
const {value, onChange, privateExample} = Shopware.Component.createExtendableSetup({
props,
context,
name: 'originalComponent',
}, () => {
const emit = defineEmits(['update:value']);
const value = ref(null);
const onChange = () => {
emit('update:value', value.value)
}
const privateExample = ref('This is a private property');
return {
public: {
value,
onChange,
},
private: {
privateExample,
}
};
});
</script>Extension override
For overrides, we created a new convention. They must match the *.override.vue pattern. *.override.vue files will be loaded automatically in your main entry file.
<template>
{# Notice the native block components #}
<sw-block extends="sw-text-field">
<sw-block-parent/>
{{ helpText}}
</sw-block>
</template>
<script setup>
// Notice Composition API imports
import { defineProps } from 'vue';
// This file would also use Shopware.Component.overrideComponentSetup
// if it would change the existing public API
const props = defineProps({
helpText: {
type: String,
required: false,
},
});
</script>Extension new component
// For this, you would also have the option to use a `*.vue` file, but you don't have to
Shopware.Component.register('your-crazy-ai-field', {
template: `
{% block your-crazy-ai-field %}
{# ... #}
{% endblock %}
`,
// Options API implementation
})Long-term direction
Once the migration is complete and the new systems have left the experimental state, registering components via Shopware.Component.register with the Options API or Twig.js templates will no longer be possible. This will only happen in a future major version.
FAQ
Will existing extensions built with the Options API continue to work?
When you only use Shopware.Component.register, yes. If you use Shopware.Component.extend/Shopware.Component.override on components that have been migrated to the Composition API, you need to use the Composition API extension approach for those.
How can I prepare my development team for the transition to Composition API?
I would recommend building a simple Vue application using the Composition API. You can do so by following official guides.
What advantages does the native block implementation offer over the current Twig.js system?
It works with native Vue.js components; therefore, it is compatible with default tooling.
Can I mix Composition API and Options API components during the transition period?
Yes, as long as you stick to the limitations from the migration paths above.
How will the migration from Twig.js templates to .vue files affect my existing component overrides?
You will need to migrate your overrides to the native block implementation once the components you are overriding have been migrated to .vue files.
What tools or resources will be available to help migrate existing components?
We'll try to provide a code mod to transition your components into SFC. This will not work for all edge cases, so you need to check and transition them manually.
Will there be any performance impact during the transition period when both systems are supported?
During our tests, we didn't experience any performance issues.
How does the new Shopware.Component.createExtendableSetup function work with TypeScript?
It has built-in TypeScript support.
What happens to existing extensions using Twig.js templates once the migration is complete?
They will stop working once Twig.js support is removed. This will only happen in a future major version.
Can I already use the native blocks and Composition API in my extensions today?
Yes! Both systems are available as experimental features. You can add new components using SFC and native blocks. But you can't extend core components using the old systems or vice versa. Keep in mind that experimental APIs can still change.
Which extensions are affected by these changes?
- Apps aren't affected at all
- Plugins need to respect the discussed changes
