Skip to main content

Static Assets Handling

In Vite, static assets such as CSS files, images, and fonts are an essential part of the development workflow. Vite provides a streamlined method for handling assets to ensure that your project is both efficient and organized. This guide explains how Vite processes assets and offers best practices for using relative and absolute paths, as well as importing assets directly in your JavaScript files.

1. How Vite Processes Static Assets​

Vite automatically processes and optimizes static assets during both the development and production stages. When assets like images, fonts, and CSS are included in your project, Vite ensures that they are correctly bundled and served to improve performance.

a. CSS Assets​

When you include CSS in your project, Vite uses native ES module support to handle styles efficiently. CSS files are processed and injected directly into the DOM during development. For production builds, Vite automatically minifies and optimizes CSS files.

You can include CSS files in your project as follows:

/* styles.css */
body {
  background-color: #f0f0f0;
}

In your JavaScript files, you can import the CSS:

import './styles.css';  // Imports the CSS file

Vite supports both global and scoped CSS styles. Scoped styles (for example, in Vue components or React's styled-components) are handled with appropriate optimizations.

b. Image Assets​

Vite processes image files like .png, .jpg, .svg, .gif, and others. During development, Vite serves them from the file system, allowing you to reference them directly in your HTML or JavaScript files.

For production, Vite optimizes the image files by hashing their filenames and automatically placing them in the build output directory (dist/). This ensures that the assets are cached efficiently in the browser.

Example: Importing Images in JavaScript​

You can import images directly in your JavaScript or CSS files:

import logo from './assets/logo.png';  // Imports the image file
const imgElement = document.createElement('img');
imgElement.src = logo;
document.body.appendChild(imgElement);

In this example, Vite automatically handles the image import and updates the src URL with the correct path.

c. Font Assets​

Vite also handles font assets like .woff, .woff2, .ttf, and .otf. Similar to images, font files are processed, optimized, and served with hashed filenames during the production build.

To include fonts, you can reference them in your CSS files:

@font-face {
  font-family: 'MyCustomFont';
  src: url('./assets/fonts/myfont.woff2') format('woff2'),
       url('./assets/fonts/myfont.woff') format('woff');
}

During the build process, Vite ensures that the fonts are served with optimized paths, and their URLs are rewritten accordingly.

2. Using Relative vs Absolute Paths​

When working with static assets, Vite supports both relative and absolute paths, and each has its own use case.

a. Relative Paths​

Relative paths are typically used when you want to refer to assets within the same directory or a subdirectory. This is ideal for local assets in your project.

Example: Using Relative Paths in HTML​

<img src="./assets/logo.png" alt="Logo">  <!-- Relative path -->

In this case, logo.png is located in the assets folder relative to the current file. This path is simple and works well during development and production.

Example: Using Relative Paths in JavaScript​

import logo from './assets/logo.png';  // Relative import

b. Absolute Paths​

Absolute paths are used when you want to refer to assets from a root level or other fixed locations in the project. Vite allows you to configure absolute paths using aliases, which makes your code more readable and less error-prone.

Example: Using Absolute Paths in HTML​

If you define an alias for the src folder, you can use an absolute path like this:

<img src="/src/assets/logo.png" alt="Logo">  <!-- Absolute path with alias -->

Here, the /src/assets/logo.png path refers to the root of the project, assuming you’ve configured an alias like @ for src in vite.config.js.

Best Practices:​

  • Use relative paths for assets that are local to the component or page.
  • Use absolute paths (via aliases) for global assets that need to be accessed from anywhere in your project.

3. Importing Assets in JavaScript Files​

Vite makes it easy to import static assets directly into your JavaScript files. This is beneficial for assets like images, icons, or even JSON files that you need to dynamically load into your application.

a. Importing Images in JavaScript​

You can import images directly into your JavaScript files, which allows you to reference them as JavaScript variables. Vite handles the processing, hashing, and path rewriting automatically.

import imageUrl from './assets/image.png';  // Import image file
const image = new Image();
image.src = imageUrl;  // Use the imported URL
document.body.appendChild(image);

b. Importing Fonts in JavaScript​

You can also import font files into JavaScript. While it's more common to include fonts in CSS, you might need to load fonts dynamically in some cases.

import './assets/fonts/myfont.woff2';  // Import font file

c. Importing Other Static Assets​

You can import other static assets such as JSON files, audio, or video in a similar manner:

import data from './assets/data.json';  // Import JSON file
console.log(data);

This is a powerful feature, as it allows assets to be bundled together with your JavaScript files, providing a more streamlined and optimized delivery in production.

4. Handling Assets in Production​

During the production build, Vite automatically optimizes and hashes asset filenames to ensure efficient caching. For example, images and fonts will have unique names based on their content (e.g., logo.abc123.png). This ensures that browsers will cache assets correctly and avoid issues with stale content.

When you run the build command (npm run build), Vite processes the assets and places them in the dist/ folder. The final output will include optimized asset files and updated paths in your HTML and JavaScript files, ensuring the best performance.

5. Conclusion​

Vite simplifies the process of handling static assets by providing automatic optimization during the build process. Whether you're working with images, fonts, or CSS, Vite ensures that your assets are bundled efficiently, with hashed filenames for caching purposes. By using relative or absolute paths and importing assets directly in JavaScript files, you can manage your project's assets with ease and focus on building your application.

Happy coding with Vite!