Installation
Polaris Vue by Ownego is a component library for Vue 3 based on Shopify Polaris style guide. We try to keep the package light-weight and easy to use (mostly similar with original Polaris Library).
Following Shopify Polaris React version: 13.5.0.
Prerequisites
- Node.js version 18 or higher. (
lts/hydrogen
is recommended) - Vue 3 version 3.3 or higher.
- VSCode is recommended, along with the official Vue extension.
Setup
npm install @ownego/polaris-vue
yarn add @ownego/polaris-vue
Usage
You can use Polaris Vue in two ways, as a plugin or as a component library. We recommend using it as a plugin.
Use as a plugin
import { createApp } from 'vue'
import PolarisVue from '@ownego/polaris-vue'
import App from './App.vue'
// This css import line will be deprecated once Vue 3 supports css injections.
import '@ownego/polaris-vue/dist/style.css'
//...
const app = createApp(App)
app.use(PolarisVue)
...
Use as a component library
<script setup>
import { List, Icon } from '@ownego/polaris-vue';
</script>
De-duplicating Vue version
PolarisVue
, other packages and your project may require access to the global Vue reference. So sometimes, you may get the runtime error message like:
TypeError: Cannot read properties of null (reading 'isCE')
renderSlot(...)
...
To avoid this, simply add dedupe: ['vue']
to your vite.config.ts
file, like below:
export default defineConfig({
resolve: {
...
dedupe: ['vue'],
},
...
});
AppProvider
The AppProvider component is required to use PolarisVue. Without it, the components in your application will not function correctly. You must wrap the root (the top) of your application in the app provider component.
The i18n
prop is required to pass the locales, you can check the supported locales here.
<template>
<AppProvider :i18n="locales">
...
<router-view />
</AppProvider>
</template>
<script setup>
import locales from '@ownego/polaris-vue/dist/locales/en.json';
</script>
Nuxt 3
We have tested support for Nuxt 3 in non-SSR mode only. To use with Nuxt 3, follow the below configuration and then use the plugin in your components/pages
.
Plugin
Create a new plugin file at <project-root>/plugins/polaris.client.ts
and update the content to following
import PolarisVue from "@ownego/polaris-vue";
import "@ownego/polaris-vue/dist/style.css";
export default defineNuxtPlugin(nuxtApp => {
nuxtApp.vueApp.use(PolarisVue);
});
Nuxt Config
Update <project-root>/nuxt.config.ts
to include following config values
export default defineNuxtConfig({
...
build: {
transpile: ["@ownego/polaris-vue"],
},
...
});
Issues & Contributions
Polaris Vue by ownego is an open source project and we are very happy to accept community contributions.
If you notice any bugs, please create issues under Issues. To contribute, please read Contributing first.
--
Missing declaration types?
At this moment, you should add the property skipLibCheck: true
to tsconfig.json
file. This will skip the check for missing declaration types.
Mostly components have been typed, but somehow if you find missing declaration types, please create an issue under Issues.
{
"compilerOptions": {
"skipLibCheck": true
}
}
Types & CSS Variables
All tokens & variables are following the Polaris Design Tokens.
For example, in the Box
component, there is background?: ColorBackgroundAlias
property. ColorBackgroundAlias
is a type that contains all the color tokens from Polaris (without prefix --p-color
), similar with original Shopify Polaris React version.
<template>
<Box background="bg-fill-success">
<p>Success</p>
</Box>
</template>
Volar & Vue language service
If you are using Volar (Vue language features) plugin, you can specify global component types by configuring compilerOptions.types
in tsconfig.json
.
{
"compilerOptions": {
"types": [
"@ownego/polaris-vue/dist/volar"
]
}
}
License
Code released under the MIT License.
Copyright © 2021 - present by Ownego.