Installation Guide

Install the effect. Own the files.

Hyperiux Vault is not designed as a heavy package that quietly expands inside your production bundle. Vault uses a source-first workflow. Effects are added directly into your project, where your team can inspect, edit, tune, and ship them with full visibility.

That matters because Vault does not only deal in static UI parts. It handles the interaction layer: motion logic, scroll behavior, cursor systems, visual rhythm, rendering details, responsive timing, and WebGL scenes. Treat that layer like a black box and you inherit someone else’s decisions.

Vault gives you the source. You make it yours.

Quick Start

Run the init command from your project root.

npx hyperiux init

Then add an effect.

npx hyperiux add phantom-image-trail

The CLI adds the files required for the selected effect. Not the whole Vault. Just the pattern you asked for.

Requirements

Before adding effects, make sure your project has the basics in place.

Vault works best in React and Next.js projects with a clean separation between server and client behavior. That is especially important for motion-heavy effects. Scroll triggers, cursor systems, layout measurements, canvas layers, and WebGL scenes usually need client-side boundaries.

TypeScript is recommended. JavaScript works, but TypeScript gives your future self fewer reasons to mutter at the screen.

Choose Your Setup Path

There are two ways to add Vault effects.

Most projects should use the CLI. Manual installation is for teams that want to inspect every file before it enters the codebase. Both paths follow the same idea:

Copy the code. Tune the motion. Ship the moment.

Method A: Install with the Hyperiux CLI

The Hyperiux CLI adds effect source files directly into your workspace. It adds the selected effect files and prompts before installing any required dependencies.

No surprise machinery.

1. Initialize Vault

Run this from the root of your project.

npx hyperiux init

This prepares your project for Vault effects.

Depending on your setup, it may create or update configuration used to place components, utilities, styles, and generated files in the right folders.

2. Add an Effect

Install the effect you want.

npx hyperiux add [effect-name]

Example:

npx hyperiux add phantom-image-trail

Vault adds the selected effect to your project files.

The exact output depends on the effect.

A text reveal should not need the same machinery as a WebGL scene. That would be suspicious.

3. Verify Installation

After adding an effect, run your project locally.

npm run dev

Then confirm:

• the component renders
• no dependency errors appear
• no hydration warnings appear
• styles are applied correctly
• the effect works in the intended page context
• the console is not quietly screaming

A demo can lie. A real page usually tells the truth.

What Vault Adds to Your Project

Vault only adds files required for the selected effect.

Depending on the pattern, files may be added to:

• components/hyperiux/
• hooks/
• lib/
• styles/
• shaders/

An effect may include:

• a React component
• supporting hooks
• utility files
• styles
• animation setup
• shader files
• dependency notes
• usage examples

Small effects stay small. Heavier effects bring the files they need.

Optional: Registry Configuration

You only need this section if your project uses a registry-based component workflow, such as a components.json setup.

If your project uses a shadcn-style registry model, add the Hyperiux registry so Vault can resolve effect source from the remote registry.

{
  "style": "default",
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "app/globals.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  },
  "registries": {
    "@hyperiux": "https://vault.hyperiux.com/r/{name}.json"
  }
}

Adjust aliases to match your project. If your components live somewhere else, tell Vault where the floor is.

Why Dependencies are Per Effect

Creative frontend work uses different tools for different jobs. Some effects may require:

• GSAP
• Motion
• Three.js
• React Three Fiber
• canvas utilities
• shader helpers
• animation hooks
• layout measurement utilities

Installing every possible dependency by default would be lazy architecture wearing a convenience hat.

Vault resolves dependencies based on the effect you add. This keeps your project cleaner, protects bundle discipline, and reduces the chance of shipping unused creative machinery into production.

Motion should create value. It should not smuggle dead weight into your build.

Method B: Manual Installation

Use manual installation when your team needs full review before code enters the repository.

This is useful for:

• enterprise teams
• locked CI/CD workflows
• security-reviewed environments
• custom monorepos
• teams with strict dependency approval
• developers who want line-by-line custody

Manual installation skips the CLI and treats each effect as a source blueprint.

Manual Install Checklist

Use this checklist before running the effect in your project:

• Copy component files.
• Copy required hooks and utilities.
• Copy styles, shaders, or assets if included.
• Install required dependencies.
• Update imports and aliases.
• Add "use client" if required.
• Confirm Tailwind content paths include Vault files.
• Test locally.
• Test in a production build.
• Check accessibility, reduced motion, and mobile behavior.

1. Choose an Effect

Go to the effects index and open the pattern you want to use. Start with the moment you need, not the tool you want.

2. Check the Implementation Notes

Before copying code, review the effect page.

Look for:

• required dependencies
• peer dependencies
• client-component requirements
• browser API usage
• Tailwind requirements
• utility imports
• CSS requirements
• mobile behavior
• reduced-motion support
• performance notes

This is where creative ambition meets the build pipeline. Read the notes. They are there to save you from 2 a.m. archaeology.

3. Install Required Dependencies

Install only what the selected effect needs.

Example:

npm install gsap motion

Or with pnpm:

pnpm add gsap motion

For a GSAP-based effect, you may need packages such as:

npm install gsap

Use the exact dependency list from the effect page. Do not install the entire creative internet just to animate a headline.

4. Copy the Source Files

Copy the component and supporting files into your project.

Example path:

components/phantom-image-trail

Some effects may also include:

• components/hyperiux/
• lib/
• hooks/
• styles/
• shaders/

Keep the structure close to the docs unless your project has a strong reason to change it.

Creative code is easier to tune when the file paths are not playing hide-and-seek.

5. Fix imports and aliases

Update import paths to match your project.

Common aliases include:

• @/components
• @/lib/utils
• @/hooks

If your project does not use these aliases, replace them with relative imports or your own path mapping.

Also check:

• Tailwind class usage
• CSS imports
• utility function paths
• shader imports
• client-only boundaries
• dynamic imports where needed

6. Test Locally

Run your dev server.

npm run dev

Then test the effect in context.

Check:

• desktop behavior
• mobile behavior
• hover fallback
• touch behavior
• reduced motion
• keyboard navigation
• layout shifts
• route changes
• hydration warnings
• console errors
• frame rate

Using an Installed Effect

After installation, import the effect from your local project files.

import PhantomImageTrail from "@/components/phantom-image-trail";

const images = [
   { src: "https://pub-8abee449136941f5b0a1cd2c014534e9.r2.dev/vault-listing-images/assets-images/h-11.jpg", alt: "Gradient 1" },
    { src: "https://pub-8abee449136941f5b0a1cd2c014534e9.r2.dev/vault-listing-images/assets-images/h-12.jpg", alt: "Gradient 2" },
    { src: "https://pub-8abee449136941f5b0a1cd2c014534e9.r2.dev/vault-listing-images/assets-images/h-13.jpg", alt: "Gradient 3" }
];

export default function Home() {
  return (
    <main className="min-h-screen overflow-hidden bg-black text-white">
      <section className="mx-auto flex min-h-screen max-w-6xl items-center px-6">
        <PhantomImageTrail images={images} />
      </section>
    </main>
  );
}

Exact props vary by effect.

Some patterns expose simple props. Others include timing controls, trigger settings, intensity values, responsive options, or dependency-specific configuration.

Check the effect page for the actual API. Then tune it until it belongs to your site.

Next.js Notes

Many Vault effects use browser APIs. That means they may need to run as client components.

If an effect uses scroll position, pointer movement, layout measurement, animation timelines, WebGL, canvas, or window, place it behind a client boundary.

"use client";

For heavier effects, consider dynamic imports.

import dynamic from "next/dynamic";

const PhantomImageTrail = dynamic(
  () => import("@/components/phantom-image-trail"),
  { ssr: false }
);

Use this when server rendering does not make sense for the effect.

Especially for WebGL.

Servers are many things. They are not GPU theatres.

Tailwind Notes

Vault effects may use Tailwind classes for layout, styling, responsive behavior, and motion-friendly structure. Make sure your Tailwind setup includes the folders where Vault files are added.

Example for Tailwind v3:

export default {
  content: [
    "./app/**/*.{ts,tsx}",
    "./pages/**/*.{ts,tsx}",
    "./components/**/*.{ts,tsx}",
    "./components/hyperiux/**/*.{ts,tsx}"
  ],
  theme: {
    extend: {}
  },
  plugins: []
};

Tailwind v4 projects may use a different configuration flow. If styles do not appear, confirm that Vault files are included in your source scanning setup.

If styles look broken, check your content paths first. It is almost always the content paths.

Troubleshooting

The effect does not render

Check:

• the import path
• the export name
• whether the component needs "use client"
• whether required dependencies are installed
• whether required styles are imported

Tailwind classes are missing

Check your Tailwind content paths or v4 source scanning setup.

Make sure the folder containing Vault files is included.

The animation works locally but breaks in production

Check:

• dynamic imports
• client-only code
• browser API usage
• hydration warnings
• environment-specific paths
• minification issues with animation libraries

The page feels slow

Profile before guessing.

Check:

• re-renders
• scroll listeners
• canvas size
• WebGL loops
• large images
• multiple effects running together
• animations that continue offscreen

If the fan starts negotiating, the effect needs attention.

The effect works on desktop but not mobile

Check:

• hover assumptions
• pointer events
• viewport height behavior
• touch support
• reduced animation path
• mobile fallback logic

Not every desktop interaction deserves a mobile twin.

Before You Ship

Installation is not the finish line. Before publishing, check:

• required dependencies are installed
• unused dependencies are removed
• the effect works in a production build
• mobile and touch behavior are acceptable
• reduced motion is respected
• keyboard navigation still works
• important content remains readable without animation
• the page has no hydration warnings
• performance is acceptable on real devices

Installation Path

For most teams:

• Initialize Vault.
• Add one effect.
• Verify the installation.
• Read the implementation notes.
• Tune the generated files.
• Test performance, accessibility, and mobile behavior.
• Ship only when the effect earns its place.

That is the workflow. Small motion. Big signal.