Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
NoSSR
✓ import NoSSR from 'vue-no-ssr'
✗ import { NoSSR } from 'vue-no-ssr'
This imports the default export of the 'vue-no-ssr' package, which is the component itself. For Vue 2, you typically register it globally or locally in `components`.
NoSSR Component Registration
✓ <script>
import NoSSR from 'vue-no-ssr';
export default {
components: {
'no-ssr': NoSSR
}
}
</script>
✗ <script>
import { NoSSR } from 'vue-no-ssr';
export default {
components: {
NoSSR
}
}
</script>
The component is intended to be used with the tag name `<no-ssr>` in templates, requiring an alias in the `components` option if imported as `NoSSR`.
Usage in template
✓ <template>
<no-ssr>
<MyClientOnlyComponent />
</no-ssr>
</template>
Wrap any component that should only render on the client-side within the `<no-ssr>` tags. You can also provide a `placeholder` slot or prop.
This example demonstrates how to use the `<no-ssr>` component to wrap `MyClientOnlyComponent`, which simulates a browser-dependent component. It shows both the `placeholder` prop and a `v-slot:placeholder` for fallback content while the main component awaits client-side hydration.
<template>
<div id="app">
<h1>My SSR-enabled Website</h1>
<no-ssr placeholder="Loading client-only content...">
<!-- This component might use browser-specific APIs or be incompatible with Node.js -->
<MyClientOnlyComponent />
<template v-slot:placeholder>
<p>This content is client-only: Loading...</p>
</template>
</no-ssr>
<p>This content is always visible (SSR and client).</p>
</div>
</template>
<script>
import Vue from 'vue';
import NoSSR from 'vue-no-ssr';
// A dummy component that would typically rely on client-side APIs
const MyClientOnlyComponent = Vue.component('MyClientOnlyComponent', {
template: '<div>Hello from the client! (Window width: {{ windowWidth }})</div>',
data() {
return { windowWidth: 0 };
},
mounted() {
if (typeof window !== 'undefined') {
this.windowWidth = window.innerWidth;
window.addEventListener('resize', this.updateWidth);
}
},
beforeDestroy() {
if (typeof window !== 'undefined') {
window.removeEventListener('resize', this.updateWidth);
}
},
methods: {
updateWidth() {
this.windowWidth = window.innerWidth;
}
}
});
export default {
name: 'App',
components: {
'no-ssr': NoSSR,
MyClientOnlyComponent
}
};
</script>
<style>
body { font-family: sans-serif; }
</style>
Debug
Known issues
breakingThe `vue-no-ssr` package and its component `<no-ssr>` were officially renamed to `vue-client-only` and `<client-only>` respectively in `vue-client-only@2.0.0`.fixMigrate to `vue-client-only` by installing `npm install vue-client-only`, then replace all instances of `<no-ssr>` with `<client-only>` and `no-ssr-placeholder` with `client-only-placeholder`.
affects: >=2.0.0 (of the successor package)
breakingThe default CSS class name for the placeholder element changed from `no-ssr-placeholder` to `client-only-placeholder` in `vue-client-only@2.0.0`.fixUpdate any custom CSS targeting `.no-ssr-placeholder` to target `.client-only-placeholder` instead after upgrading to `vue-client-only`.
affects: >=2.0.0 (of the successor package)
gotchaThis package (`vue-no-ssr`) does not provide official TypeScript types. While it can be used in TypeScript projects, you may need to declare types manually or rely on `any`.fixIf using TypeScript, consider upgrading to `vue-client-only@2.1.0` or higher, which introduced official TypeScript types. For `vue-no-ssr`, you might need to add a `declarations.d.ts` file with `declare module 'vue-no-ssr';`.
affects: <2.1.0 (of the successor package)
Errors
Common errors & fixes
Failed to mount component: template or render function not defined.
The `<no-ssr>` component was imported but not registered in the Vue component's `components` option.
fixEnsure `NoSSR` is correctly imported and registered: `import NoSSR from 'vue-no-ssr'; export default { components: { 'no-ssr': NoSSR } }`. [Vue warn]: Unknown custom element: <no-ssr> - did you register the component correctly?
The Vue instance cannot find the `<no-ssr>` component, often due to incorrect registration or a typo in the tag name.
fixVerify that `NoSSR` is correctly imported and registered in the `components` option, and that the tag used in the template matches the registered name (e.g., `'no-ssr'`).
Audit
Dependencies
vuerequiredPeer dependency as a Vue component library.