Vue No SSR

1.1.1 · renamed · verified Sun Apr 19

Vue No SSR was a component designed for Vue.js applications utilizing Server-Side Rendering (SSR) to wrap components that should only be rendered on the client side. Its primary function was to prevent hydration mismatches and allow browser-specific code or libraries to function correctly without causing errors during the SSR build process. The package's last version under this name was 1.1.1, released in early 2019. It was succeeded by `vue-client-only` in its 2.0.0 release, which is actively maintained. This component provided a simple API, allowing for fallback content (placeholders) to be displayed during SSR until the client-side component was mounted. It solved a common problem in isomorphic Vue applications where certain elements or third-party libraries are not compatible with Node.js environments.

Common errors

```
Failed to mount component: template or render function not defined.
```
cause The `<no-ssr>` component was imported but not registered in the Vue component's `components` option.

fix Ensure `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?
```
cause The Vue instance cannot find the `<no-ssr>` component, often due to incorrect registration or a typo in the tag name.

fix Verify 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'`).

Warnings

breaking The `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`.
Fix: Migrate 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`.
breaking The default CSS class name for the placeholder element changed from `no-ssr-placeholder` to `client-only-placeholder` in `vue-client-only@2.0.0`.
Fix: Update any custom CSS targeting `.no-ssr-placeholder` to target `.client-only-placeholder` instead after upgrading to `vue-client-only`.
gotcha This 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`.
Fix: If 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';`.

Install

npm install vue-no-ssr npm
yarn add vue-no-ssr yarn
pnpm add vue-no-ssr pnpm

Imports

NoSSR
wrong:
```
import { NoSSR } from 'vue-no-ssr'
```
correct:
```
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

wrong:

<script>
import { NoSSR } from 'vue-no-ssr';
export default {
  components: {
    NoSSR
  }
}
</script>

correct:

<script>
import NoSSR from 'vue-no-ssr';
export default {
  components: {
    'no-ssr': 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.

Quickstart

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>

view raw JSON →