nuxt-safe-render

Find SSR-unsafe Nuxt code before hydration breaks.

nuxt-safe-render is a Visual Studio Code extension for Nuxt and Vue projects. It helps detect code patterns that may break during server-side rendering, produce hydration mismatches, or behave differently between the server and the browser.

The extension analyzes code locally inside VS Code and reports findings as editor diagnostics.

Why This Extension Exists

Nuxt applications can run code in both server and client contexts.

Some code is safe in the browser but unsafe during SSR. Other code may render one value on the server and a different value on the client, which can lead to hydration mismatches, flickering UI, broken DOM identity, or runtime errors.

nuxt-safe-render is designed to catch these issues earlier, while you are editing code.

The goal is not to blindly suggest <ClientOnly> everywhere. The goal is to help you understand what is risky, why it is risky in a Nuxt SSR context, and which Nuxt-safe fix direction may be appropriate.

Features

nuxt-safe-render reports SSR and hydration risks directly in VS Code.

It can help detect patterns such as:

• Browser globals used in SSR-sensitive code.
• Browser APIs used where server-side rendering may execute the code.
• Browser-only packages imported from SSR-sensitive files.
• Explicit client component imports that may indicate an unsafe client/server boundary.
• Non-deterministic values rendered during SSR.
• Locale or timezone-sensitive formatting that may differ between server and client.
• Viewport or device-based rendering logic that can produce different server and client output.
• Random IDs or generated keys that may not stay stable across SSR and hydration.
• Non-deterministic sorting or object iteration that affects rendered output.
• Server/client state synchronization risks.

Findings are displayed in the editor and in the VS Code Problems panel.

Example Risk Patterns

Browser-only global in SSR-sensitive code

const width = window.innerWidth;

window exists only in the browser. If this code runs during SSR, it may throw an error or behave differently from the browser.

Non-deterministic value in rendered output

const id = Math.random();

Random values can differ between the server render and the client hydration pass.

Time-based rendered value

const createdAt = new Date().toLocaleString();

Date, locale, and timezone formatting may produce different output across environments.

Viewport-based rendering

<template>
  <DesktopMenu v-if="width > 1024" />
</template>

<script setup>
const width = window.innerWidth;
</script>

The server does not know the browser viewport. Rendering different structure on the server and client can cause hydration mismatch.

Generated key or ID

<template>
  <label :for="inputId">Email</label>
  <input :id="inputId" />
</template>

<script setup>
const inputId = `input-${Math.random()}`;
</script>

Generated IDs can break hydration stability and DOM relationships such as label / for or ARIA references.

Supported File Types

The extension currently analyzes:

• Vue single-file components (.vue)
• JavaScript files (.js)
• TypeScript files (.ts)

How It Works

nuxt-safe-render runs locally inside VS Code.

It reads the currently opened document and, when needed, relevant local workspace files for static analysis. It then publishes diagnostics through the VS Code diagnostics system.

The extension does not require a login, does not upload source code, and does not use an external analysis service.

Usage

Open a Vue, JavaScript, or TypeScript file in VS Code.

The extension can scan files automatically when they are opened or saved.

You can also run a manual scan:

1. Open the Command Palette.
2. Run:

Nuxt Safe Render: Scan Current File

The command ID is:

nuxt-safe-render.scanCurrentFile

Diagnostics

Diagnostics may include information such as:

• The detected problem.
• Why the pattern may be risky.
• The SSR/client context.
• The possible runtime or hydration risk.
• A confidence level.

Diagnostics are intended to help you review suspicious patterns. They are not a guarantee that the code is broken.

Recommended Fix Direction

The correct fix depends on the specific code and Nuxt context.

Possible fix directions include:

• Move browser-only code into onMounted.
• Guard browser-only access with import.meta.client.
• Move truly client-only logic into .client.ts or .client.vue.
• Wrap a component with <ClientOnly> only when the whole component must render on the client.
• Avoid rendering non-deterministic values during SSR.
• Use stable values for IDs, keys, attributes, and rendered content.
• Use useState when a value must be shared consistently between SSR and hydration.
• Avoid viewport/device-based render decisions before hydration is safe.
• Use explicit locale/timezone options when formatting rendered values.
• Keep server-only and client-only code separated.

Do not treat every warning as an automatic instruction to add <ClientOnly>. Review the context and choose the smallest correct Nuxt fix.

What This Extension Does Not Do

nuxt-safe-render does not automatically rewrite your code.

It does not guarantee that every SSR issue or hydration mismatch will be detected.

It does not guarantee that every diagnostic is correct for every Nuxt project setup.

It does not replace testing, code review, production validation, or framework-specific review.

Privacy

nuxt-safe-render is designed to run locally inside VS Code.

According to the current implementation:

• It does not upload source code, project files, workspace data, or analysis results to external servers.
• It does not include telemetry, analytics, tracking, or crash reporting.
• It does not require login, user accounts, subscriptions, or license activation.
• It does not use AI APIs, cloud backends, or external analysis services.

For more details, see PRIVACY.md.

Security

If you believe you have found a security vulnerability, please report it responsibly.

You can report security issues through GitHub Security Advisories, if available in the project repository, or by email:

rafiariel000@gmail.com

For more details, see SECURITY.md.

Requirements

This extension requires a compatible version of Visual Studio Code as declared in package.json.

The current extension manifest declares:

"engines": {
  "vscode": "^1.118.0"
}

The extension is intended for Nuxt and Vue projects, but it can also analyze JavaScript and TypeScript files that contain SSR-sensitive patterns.

Extension Settings

This extension does not currently contribute custom VS Code settings.

Commands

This extension contributes the following command:

Nuxt Safe Render: Scan Current File

Command ID:

nuxt-safe-render.scanCurrentFile

Known Limitations

nuxt-safe-render is an advisory static-analysis tool.

Known limitations include:

• It may report false positives.
• It may miss some SSR or hydration issues.
• It may not fully understand every project-specific abstraction.
• It may not fully understand every third-party package behavior.
• It may not detect issues that only appear at runtime.
• It may not account for every Nuxt version, module, build setup, or deployment environment.
• Advanced Vue template preprocessors or non-standard SFC template languages may not be fully supported.

Always review diagnostics in the context of your own project.

Troubleshooting

If diagnostics do not appear:

1. Make sure the active file is a .vue, .js, or .ts file.
2. Save the file and check the Problems panel.
3. Run Nuxt Safe Render: Scan Current File from the Command Palette.
4. Make sure the workspace is trusted in VS Code.
5. Check that the extension is enabled.

Changelog

See CHANGELOG.md for release history.

Support

For bugs, questions, or feature requests, use the issue tracker in the project repository once it is available.

Until a public repository is available, use the contact method provided in the Marketplace listing.

Third-Party Notices

This extension uses third-party open-source dependencies.

For more details, see THIRD-PARTY-NOTICES.txt.

Privacy & Terms

• Privacy Policy: see PRIVACY.md
• Terms of Use: see TERMS.md
• Third-party notices: see THIRD-PARTY-NOTICES.txt
• Security Policy: see SECURITY.md
• Changelog: see CHANGELOG.md
• License: see LICENSE

License

This project is licensed under the MIT License.

See LICENSE for details.