Dependencies

Bring the engine you need. Not the whole garage.

Hyperiux Vault is source-first. Effects are added into your project as editable files, not hidden behind a sealed package.

That matters for dependencies.

A scroll reveal, a magnetic cursor, and a WebGL scene should not carry the same technical weight. Some effects need only React and CSS. Some need GSAP or Motion. Some need Three.js, React Three Fiber, shaders, canvas, and a little respect for the GPU.

Vault keeps dependency requirements visible and scoped to the effect you install.

No surprise engines. No drive-by Three.js.

The Dependency Model

Vault dependencies fall into two groups.

Structural requirements are expected across Vault. Peer engines are added only when an effect needs them.

That keeps the project cleaner, the bundle easier to reason about, and the interaction layer easier to own.

Motion should earn its place in the build.

Structural Requirements

Every Vault effect assumes a modern React setup.

Vault works best in projects that separate server and client behavior clearly.

That is especially important for effects that use:

• scroll position
• pointer movement
• layout measurements
• animation timelines
• canvas
• WebGL
• browser APIs

If an effect touches the browser directly, it usually needs a client boundary.

"use client";

Servers are many things.

They are not GPU theatres.

Peer Engines

Peer engines are libraries used by specific Vault effects.

They are not installed globally for every pattern. They are declared by the effect that needs them.

Not every effect in a category uses every engine listed above.

Check the effect page before installing.

A text reveal should not need a 3D pipeline. A WebGL scene probably will.

That is not bloat. That is choosing the right machine for the trick.

How the CLI Handles Dependencies

When you add an effect with the Hyperiux CLI, the CLI reads the effect manifest.

npx hyperiux add phantom-image-trail

The manifest defines what the effect needs, including:

• source files
• utility files
• styles
• peer dependencies
• setup notes
• client-component requirements
• browser or rendering assumptions

If a dependency is required, the CLI makes it visible during installation.

Depending on your CLI configuration, Vault either prompts before installing missing packages or prints the exact package-manager command so you can install them manually.

Example:

npm install gsap

Or:

pnpm add gsap

The point is simple: dependencies should be attached to the effect that uses them.

Not sprayed across your project because one day you might animate something.

Manual Dependency Installation

If you install an effect manually, install only the dependencies listed on that effect page.

Example for a GSAP-based effect:

npm install gsap

Example for a Motion-based effect:

npm install motion

Example for a WebGL or React Three Fiber effect:

npm install three @react-three/fiber @react-three/drei

Use your package manager of choice.

pnpm add gsap

yarn add gsap

bun add gsap

Do not install the entire creative internet just to animate a headline.

Recommended Versions

The effect page or registry manifest is the source of truth.

The example below shows the shape of a typical dependency block, not a universal version policy:

{
  "dependencies": {
    "gsap": "^3.12.5",
    "motion": "^12.0.0",
    "three": "^0.160.0",
    "@react-three/fiber": "^8.15.0",
    "@react-three/drei": "^9.90.0"
  }
}

Use the versions listed by the effect you install.

Animation and rendering libraries move. Your lockfile remembers.

Make sure it remembers the right thing.

Motion and Framer Motion

Some older examples may reference framer-motion.

Newer Vault effects may use motion.

Use the package specified by the effect page.

Do not install both unless your project actually needs both.

Two animation libraries in one project can be fine.

Two animation libraries because nobody checked the docs is how bundle weight learns to reproduce.

Bundle Behavior

Vault is designed to keep effects local and modular.

Adding one effect should not make every page pay for every other effect.

Still, source ownership means you are responsible for how the effect is imported, rendered, and bundled inside your app.

To keep things clean:

• import effects only where they are used
• avoid global imports for page-specific effects
• lazy-load heavy WebGL or canvas components
• keep browser-only code inside client components
• remove unused dependencies
• run production builds before judging performance

The install is the beginning.

The bundle is where the truth comes out.

Tree-Shaking

Vault effect files are structured to support clean imports.

That helps bundlers remove unused code, but tree-shaking is not magic.

It depends on:

• how you import files
• whether modules have side effects
• how dependencies are packaged
• whether code is used globally
• whether the effect runs on every page
• your framework and bundler configuration

Prefer direct imports.

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

Avoid importing a full local index of effects into a shared layout unless you actually need it there.

Your layout is not a storage unit.

WebGL and Canvas Dependencies

WebGL and canvas effects need extra care.

They may depend on:

• three
• @react-three/fiber
• @react-three/drei
• shader files
• texture assets
• browser APIs
• device pixel ratio
• resize observers
• animation loops

For Next.js, heavy WebGL components often work best with 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.

Especially when the component needs window, document, canvas, WebGL, or GPU-backed rendering.

CSS and Tailwind Dependencies

Vault effects may use Tailwind classes for layout, styling, spacing, responsive behavior, and visual states.

For Tailwind v3 projects, make sure Tailwind scans the folder where Vault files are installed.

Example:

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

Tailwind v4 projects may handle configuration differently depending on the setup.

If your project does not use a traditional Tailwind config file, make sure the Vault directory is included through your CSS or project configuration entry point.

If an effect renders but looks broken, check Tailwind content paths first.

It is usually that.

Then check CSS variables. Then check whether you copied the whole effect.Then, briefly, blame yourself.

Performance Impact

Dependencies are not just installation details.

They affect runtime behavior.

Watch for:

• layout shifts
• expensive scroll listeners
• unnecessary re-renders
• large canvas layers
• WebGL loops running offscreen
• multiple heavy effects on one page
• animation work during route transitions
• large image and texture assets

Prefer transform-based motion where possible.

Good properties:

transform: translate3d(0, 0, 0);
transform: scale3d(1, 1, 1);
transform: rotate3d(0, 1, 0, 15deg);
opacity: 1;

Riskier properties for frequent animation:

• width
• height
• top
• left
• margin
• padding

Move pixels intelligently. Do not ask the browser to rebuild the room every frame. For deeper testing guidance, see Performance Notes.

Reduced Motion

Motion should respect the person watching it.

Effects that include movement should provide a calmer path for users who prefer reduced motion.

That may mean:

• disabling movement
• reducing distance
• shortening transitions
• removing parallax
• disabling cursor trails
• showing content immediately
• replacing motion with a simple state change

Use the browser preference.

A scoped fallback is safer than applying reduced-motion rules globally across the whole app.

@media (prefers-reduced-motion: reduce) {
  .hyperiux-effect,
  .hyperiux-effect * {
    animation-duration: 0.01ms;
    animation-iteration-count: 1;
    transition-duration: 0.01ms;
    scroll-behavior: auto;
  }
}

Use a global selector only if you intentionally want a site-wide reduced-motion policy.

For component-level behavior, check reduced motion in JavaScript when needed.

const prefersReducedMotion =
  typeof window !== "undefined" &&
  window.matchMedia("(prefers-reduced-motion: reduce)").matches;

Reduced motion is not the boring version.

It is the considerate version.

For deeper guidance, see Reduced Motion.

Accessibility Impact

Dependencies are not only a bundle concern.

They affect how the interaction behaves.

When adding motion-heavy effects, check that:

• content remains readable without animation
• keyboard navigation still works
• focus states remain visible
• semantic structure stays intact
• animation does not block content
• screen readers can access content in a logical order
• hover-only behavior has a touch or keyboard fallback

The motion layer should support the page.

It should not hold the content hostage.

For deeper implementation guidance, see Accessibility.

Checking Dependencies with Doctor

Use the CLI doctor command to inspect your setup.

npx hyperiux doctor

The doctor command checks common dependency and setup issues.

It can report:

• missing packages
• broken import aliases
• missing Tailwind content paths
• missing CSS entry files
• client-component requirements
• browser-only code in server components
• duplicate effect files
• registry access issues
• WebGL or canvas setup warnings

Example output:

Hyperiux Doctor
Project detected: Next.js
Tailwind config found
Components alias resolved
Missing dependency: gsap
phantom-image-trail uses browser APIs and should be rendered inside a client boundary

Next steps:
npm install gsap
Add "use client" to the component entry file.

Run it after adding effects, moving files, upgrading effects, or changing dependencies.

It will not fix your taste. It will fix a surprising number of setup issues.

Dependency Troubleshooting

Missing Dependency

Install the package listed by the effect page or CLI output.

npm install gsap

Then run:

npx hyperiux doctor

Duplicate Animation Packages

Check whether the project uses both framer-motion and motion.

Keep both only if required.

If not, standardize around the package used by your installed effects.

Tailwind Styles Do Not Apply

Make sure Tailwind scans the Vault directory.

content: [
  "./components/hyperiux/**/*.{ts,tsx}"
]

For Tailwind v4, check your CSS or project configuration entry point instead of assuming a traditional config file exists.

WebGL Effect Crashes on Load

Check:

• client component boundary
• dynamic import setup
• WebGL browser support
• texture or shader paths
• device memory limits
• missing Three.js dependencies

Effect Works Locally but Fails in Production

Check:

• lockfile changes
• dependency versions
• dynamic imports
• browser-only code
• build output
• minification issues
• environment-specific paths

Bundle Size Jumped

Check:

• which effect introduced the dependency
• whether the effect is imported globally
• whether a WebGL scene is loaded on every page
• whether unused effects are still imported
• whether old dependencies can be removed

Run your bundle analyzer if the project uses one. Guessing is not profiling.

Dependency Rules Worth Keeping

Use these as a final check before shipping.

• Install only what the effect needs.
• Use the effect page or registry manifest as the source of truth.
• Keep heavy effects out of shared layouts unless required.
• Lazy-load WebGL and canvas when possible.
• Scope reduced-motion fallbacks where possible.
• Respect accessibility requirements.
• Test mobile behavior.
• Remove unused dependencies.
• Check production builds.
• Run npx hyperiux doctor after changes.

Small motion. Big signal. Small bundle. Better signal.