Registry / devops / vite-plugin-public-path

vite-plugin-public-path

library1.1.0jsnpmunverified

A Vite plugin that provides the equivalent of Webpack's __webpack_public_path__, allowing dynamic resolution of asset base path at runtime (e.g., loading from CDN). Version 1.1.0, actively maintained with steady updates. Ships TypeScript types and supports both modern and legacy builds (via @vitejs/plugin-legacy). Requires Vite >=2.8 as a peer dependency. Key differentiator: works for index.html and legacy bundles, not just JavaScript chunks.

devops

npm install vite-plugin-public-path

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-PUBLIC

vite-plugin-public-path

devopsjavascriptv1.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

publicPath (default import)

✓ import publicPath from 'vite-plugin-public-path'

✗ const publicPath = require('vite-plugin-public-path')

ESM-only; not available as CommonJS. TypeScript types included.

type PublicPathOptions

✓ import type { PublicPathOptions } from 'vite-plugin-public-path'

Only used for type assertions or custom config; not needed for basic usage.

Plugin usage in vite.config.ts

✓ publicPath({ publicPathExpression: 'window.__publicPath', html: true })

✗ new PublicPathPlugin({ ... })

The plugin is a function, not a class. Instantiate by calling it with options.

Configures Vite to use a dynamic public path during production builds, with a placeholder base to be replaced at runtime via a global variable.

// vite.config.ts import { defineConfig } from 'vite'; import publicPath from 'vite-plugin-public-path'; export default defineConfig({ base: process.env.NODE_ENV === 'production' ? '/__PLACEHOLDER__/' : '/', plugins: [ publicPath({ publicPathExpression: 'window.__publicPath', html: true, }), ], }); // In your HTML head: <script> window.__publicPath = 'https://cdn.example.com/'; </script>

Debug

Known issues

gotchaThe plugin must be placed after almost all plugins, except for HTML minifiers like vite-plugin-html-minifier-terser.

fix

Order plugins: other plugins first, then publicPath(), then minifier plugins.

affects: >=1.0.0

gotchaThe `base` placeholder must be unique and not appear in your application code or assets to avoid unintended replacements.

fix

Use a distinctive placeholder like '/__VITE_BASE__/' and ensure it does not exist in your source.

affects: >=1.0.0

deprecatedNo deprecations known; check GitHub for any future changes.

fix

N/A

affects: >=1.0.0

gotchaWhen using `html: false`, the generated index.html will contain the base placeholder, making it unusable unless processed manually.

fix

Either set `html: true` or provide a string replacement for `html` option to replace the placeholder.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'vite-plugin-public-path'

Missing installation or wrong import syntax in CommonJS environment.

fix

Ensure package is installed: npm i -D vite-plugin-public-path. Use ESM (import) syntax in vite.config.ts.

Error: Vite's base placeholder appears in built assets

Placeholder string is not unique and was replaced incorrectly in non-placeholder contexts.

fix

Use a more unique placeholder, e.g., '/__VITE_DYNAMIC_BASE__/', and verify it is not present in source code or asset contents.

Error: __public_path is not defined (runtime ReferenceError in browser)

The global variable used in `publicPathExpression` is not declared before the plugin's injected scripts run.

fix

Add a <script> tag in the HTML <head> that defines the variable before any other scripts (e.g., <script>window.__publicPath = '...';</script>).

Error: Dynamic import not using correct base path

The plugin may not cover dynamic imports in legacy bundles or certain edge cases.

fix

Ensure you are using @vitejs/plugin-legacy and that the plugin is configured for legacy builds. Check GitHub issues for known limitations.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

viterequiredPeer dependency; required for the plugin to function (version >=2.8)

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/Menci/vite-plugin-public-path ↗

packagevite-plugin-public-path ↗

homepagehttps://github.com/Menci/vite-plugin-public-path#readme ↗