# Install and configure Impact Nova

Use these steps to add Impact Nova to an existing project. Run the commands in your project root and apply the code changes to your entry file and layout.

## 0. Scaffold a new app (recommended)

**`create-impact-nova@^1.4.9`** is on npm. Scaffold auto-detects dependency mode:

| Where you run | `impact-nova` dependency |
|---------------|--------------------------|
| Published CLI / MCP (outside monorepo) | `impact-nova@^2.5.10` from npm (`latest` tag) |
| Inside impact-nova monorepo | `file:` link to repo root |

```bash
npx create-impact-nova my-dashboard
cd my-dashboard
npm run dev
```

MCP: **`scaffold_impact_nova_app`** with `projectName` and optional `modules[]` from the user prompt.

**Overrides:** CLI `--from-npm` · `--link-monorepo` · MCP `usePublishedPackages: true | false`

```bash
npx create-impact-nova my-dashboard --from-npm
```

Base template is shell-only (Home + shared primitives). Feature pages come from recipes — see `create-impact-nova/recipes/README.md`.

**Local link in an existing app** (manual):

```bash
npm install impact-nova@file:../path-to-impact-nova-repo
```

Run `npm run build` in the impact-nova repo after design-system changes.

## 1. Install the package and peer dependencies

```bash
npm install impact-nova impact-nova-icons
npm install react@^19 react-dom@^19
```

**Required peers:** `react@^19`, `react-dom@^19`, `impact-nova-icons@^0.1.1`

**Optional peers** (install when you use these features):

| Package | Version | When needed |
|---------|---------|-------------|
| `ag-grid-community` | `36.0.1` | AG Grid types/API (pin with react + enterprise) |
| `ag-grid-react` | `36.0.1` | DataTable / AG Grid |
| `ag-grid-enterprise` | `36.0.1` | Enterprise grid features |
| `highcharts` | `^12` | Chart component |
| `highcharts-react-official` | `^3` | Chart component |
| `highcharts-border-radius` | `^0.0.4` | Rounded chart corners |

If you use AG Grid or Highcharts in your app, also install:

```bash
npm install ag-grid-community@36.0.1 ag-grid-react@36.0.1 ag-grid-enterprise@36.0.1
# Optional, for charts:
npm install highcharts@^12 highcharts-react-official@^3 highcharts-border-radius@^0.0.4
```

## 2. Import styles in your root entry

In your app root (e.g. `main.tsx`, `App.tsx`, or `layout.tsx`), **import the CSS before your app component**:

```tsx
import 'impact-nova/dist/impact-nova.css';
import App from './App';
// ... rest of your bootstrap
```

## 3. Add Manrope font (recommended)

In your `index.html` or layout:

```html
<link href="https://fonts.googleapis.com/css2?family=Manrope:wght@200..800&display=swap" rel="stylesheet" />
```

In your global CSS or Tailwind base:

```css
@layer base {
  body {
    font-family: 'Manrope', sans-serif;
  }
}
```

## 4. Wrap your app with providers (recommended)

Mount **`ImpactNovaProviders`** once at the app root. It bundles i18n (`ImpactNovaI18nProvider`) and `TooltipProvider` (required for tooltips since v2.0.8):

```tsx
import { ImpactNovaProviders } from 'impact-nova/form';

function Root() {
  return (
    <ImpactNovaProviders locale="en">
      <App />
    </ImpactNovaProviders>
  );
}
```

For another locale, pass a locale pack:

```tsx
import { ImpactNovaProviders } from 'impact-nova/form';
import { de } from 'impact-nova/locale/de';

<ImpactNovaProviders locale="de" messages={de}>
  <App />
</ImpactNovaProviders>
```

**Barrel exception:** locale packs may use `import { de } from 'impact-nova'`. All UI components still use subpaths (see §5).

## 5. Subpath imports (recommended)

Prefer subpath imports in feature code for tree-shaking:

```tsx
import { Button } from 'impact-nova/button';
import { Card, CardContent } from 'impact-nova/card';
import { DataTable, DataTableContent, useDataTable } from 'impact-nova/data-table';
import { CheckCircle } from 'impact-nova-icons';
```

The barrel `import { Button } from 'impact-nova'` still works but pulls a larger module graph. **Use subpaths for all UI components**; reserve the barrel for locale packs at app root only. Use `ImpactNovaProviders` from `impact-nova/form` for app setup.

## 6. Using Impact Nova with CSS or SCSS (no Tailwind)

If your app uses **plain CSS or SCSS** and does **not** use Tailwind, you can still use Impact Nova. Tailwind is optional. Impact Nova ships a single built CSS file (no SCSS source).

- **Import the library CSS** in your app root (e.g. `main.tsx`, `App.tsx`):
  ```tsx
  import 'impact-nova/dist/impact-nova.css';
  ```
  **CSS split exports** (optional, for layered theming): `impact-nova/impact-nova-tokens.scss`, `impact-nova/impact-nova-base.scss`, `impact-nova/impact-nova-components.css`
  Or from your main stylesheet: `@import 'impact-nova/dist/impact-nova.css';` in your main.css or main.scss.
- **Component styling** comes from Impact Nova's CSS. Use each component's `variant` and `size` props; no Tailwind classes are required.
- **Your layout and spacing** stay in your CSS or SCSS (margins, padding, flexbox, grid). Use your usual class names; the design system does not require Tailwind utilities.
- **Manrope font:** Add the font link in `index.html` and in your CSS/SCSS set `body { font-family: 'Manrope', sans-serif; }` (see section 3).
- **Summary:** No Tailwind, no Tailwind config. Load `impact-nova.css` once; use components with their props; use your existing CSS/SCSS for the rest.

## 6b. Theming in consumer apps

| Surface | What ships |
|---------|------------|
| **npm / consumer apps** | **Impact Light** only — `import 'impact-nova/dist/impact-nova.css'` (from `src/theme/tokens/light.json`) |
| **Storybook / dev** | 10 curated **theme presets** (Impact Dark, Midnight, Ocean, …) — preview switcher only |

**Do not** copy Storybook preset JSON or `theme-presets.ts` into consumer apps. Presets are not in the published package.

**Custom branding:** override CSS variables on `:root` or a scoped class (e.g. `.my-brand`). Use Storybook **Theme Builder** / **Token Catalog** to explore tokens, then export CSS/JSON for your overrides.

## 7. Using Impact Nova with Webpack

If your app is built with **Webpack** (including Create React App, which uses Webpack):

- **CSS import:** Webpack will bundle the library CSS as long as you have a rule for `.css`. Ensure your config includes something like:
  ```js
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader'],
        // or with MiniCssExtractPlugin:
        // use: [MiniCssExtractPlugin.loader, 'css-loader'],
      },
      // ... other rules (e.g. for .tsx, .js)
    ],
  },
  ```
  Then in your root component or entry:
  ```tsx
  import 'impact-nova/dist/impact-nova.css';
  ```
- **Create React App (CRA):** No extra config. Add `import 'impact-nova/dist/impact-nova.css';` in `index.tsx` or `App.tsx`.
- **Dedupe React / AG Grid:** If you see “multiple copies of React” or AG Grid issues, use Webpack’s `resolve.alias` so the app uses a single version:
  ```js
  resolve: {
    alias: {
      react: path.resolve(__dirname, 'node_modules/react'),
      'react-dom': path.resolve(__dirname, 'node_modules/react-dom'),
      // If using AG Grid:
      'ag-grid-react': path.resolve(__dirname, 'node_modules/ag-grid-react'),
      'ag-grid-community': path.resolve(__dirname, 'node_modules/ag-grid-community'),
      'ag-grid-enterprise': path.resolve(__dirname, 'node_modules/ag-grid-enterprise'),
    },
  },
  ```
- **Tailwind + Webpack:** If you use Tailwind, add the Impact Nova preset and include the package in `content` (see section 7 below).

## 8. Optional: extend Tailwind with Impact Nova preset

If your project uses Tailwind and you want the same theme (colors, radius), extend your `tailwind.config.js` with the preset from the package:

```js
// tailwind.config.js
import impactNovaPreset from 'impact-nova/tailwind.config.js';
// → dist/tailwind.config.js (bundled theme; no package src/ required)

export default {
  presets: [impactNovaPreset],
  content: [
    './index.html',
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/impact-nova/dist/**/*.js',
  ],
  // ... rest of your config
};
```

## Summary checklist

- [ ] `npm install impact-nova impact-nova-icons` (and react, react-dom; optional: ag-grid, highcharts)
- [ ] `import 'impact-nova/dist/impact-nova.css'` in root entry (or @import in main.css/main.scss if using CSS or SCSS without Tailwind; see §6)
- [ ] Add Manrope font link and body font-family
- [ ] Wrap app with `<ImpactNovaProviders locale="en">` from `impact-nova/form`
- [ ] Use subpath imports in feature code (see §5)
- [ ] (Optional) Add Tailwind preset and content path for impact-nova
- [ ] **Webpack:** Ensure a CSS rule (style-loader + css-loader) and, if needed, resolve.alias for React/AG Grid

After this, import components via subpaths: `import { Button } from 'impact-nova/button';`

## 9. Dashboard app shell (optional)

To scaffold a full dashboard (sidebar, header, breadcrumb, filters), read resource **`impact-nova://layout`** or call `get_real_world_patterns` with `topic: "layout"`. Use `Layout` from `impact-nova/layout` — not `DynamicLayout` (grid/flex utility only).