# adaptable-setup

Canonical page: https://www.adaptabletools.com/docs/getting-started-ai-skills-setup

- Adds AdapTable to a project for the first time
- Can be a new AdapTable + AG Grid app from nothing, from a dataset, or wired onto an existing AG Grid instance

Use the adaptable-setup AI Skill to add AdapTable to a project for the first time.

This can be either of:

- a new AdapTable and AG Grid application
  
  The Grids can be created from nothing, or from a dataset (CSV, Excel, JSON, a REST endpoint) or from a description
  
- a new AdapTable wired onto an existing AG Grid Enterprise Grid

- Do not use this for a project that already has AdapTable (use `adaptable-dev` for that)
- Nor to upgrade AdapTable (use `adaptable-upgrade`, and `ag-update` when AG Grid must move too)

<AiSkill skill="adaptable-setup" embedded>

add AdapTable to this AG Grid app
<br/>
create a trade blotter from this CSV

<!-- framework: vanilla -->
### Vanilla

set up AdapTable in a new TypeScript project with rows fetched from `https://api.example.com/trades`
<!-- /framework -->
<!-- framework: react -->
### React

set up AdapTable in a new React project with rows fetched from `https://api.example.com/trades`
<!-- /framework -->
<!-- framework: angular -->
### Angular

set up AdapTable in a new Angular project with rows fetched from `https://api.example.com/trades`
<!-- /framework -->
<!-- framework: vue -->
### Vue

set up AdapTable in a new Vue project with rows fetched from `https://api.example.com/trades`
<!-- /framework -->
</AiSkill>

## How it Works

The agent looks at the project and follows one of three paths:

| Path | Project has               | The agent                                                                                                                                                                                                                                                               |
| ---- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A    | An AG Grid Enterprise app | <ul><li>Keeps your column definitions and Grid options</li><li>Creates the Grid through AdapTable</li><li>Moves the column layout into an AdapTable Layout</li><li>Column styling such as `cellStyle` and `valueFormatter` stays unless you ask to convert it</li></ul> |
| B    | A project without a Grid  | <ul><li>Adds AG Grid and AdapTable</li><li>Types the columns from your data</li></ul>                                                                                                                                                                                   |
| C    | Nothing yet               | <ul><li>Shows you the command that creates the project (e.g. `npm create vite@latest` or `ng new`)</li><li>Runs it, or lets you run it</li><li>Then it continues as path B</li></ul>                                                                                    |

The workflow is as follows:

- On every path it checks the AG Grid version is one AdapTable pairs with, and which package to install
- It keeps Initial State small: one Layout with every column, and Dashboard with Layout and Export toolbars
- It tells you that State is saved in the browser by default
- Then it builds the app, runs it and checks the page

It finishes with a short summary of where the Options, the Initial State and the keys live.

From there, `adaptable-dev` takes over.

### What the Agent Asks You

The agent asks you questions and stops in the chat and waits for an answer.

- It does not ask on every step
- It asks only when a choice is hard to undo, and then carries on

| When                                                                      | What it asks                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AG Grid is Community, or using a version that AdapTable doesn't pair with | <ul><li>Whether to upgrade AG Grid first, or stop</li><li>It will not install AdapTable onto a Grid it cannot pair with</li></ul>                                                                                                                                                             |
| Before it writes any files                                                | <ul><li>The licence keys, or trial placeholders</li><li>Which column is the unique key, if none is obvious (it asks this once)</li></ul>                                                                                                                                                      |
| It is creating a new Grid                                                 | <ul><li>Where the data comes from: a file, a URL, or demo data</li><li>An existing Grid already has its data</li><li>Once it has read the data, the columns it inferred: names, types, and whether they can be empty</li><li>You confirm or correct them before it writes the files</li></ul> |
| The project already has AG Grid                                           | <ul><li>Which column settings move into an AdapTable Layout</li><li>The default is all of them, because otherwise the Layout and the column definition disagree</li><li>Which styling to turn into AdapTable formatting (default is none)</li></ul>                                           |
| The Grid is in place                                                      | <ul><li>Whether to add extras from the docs demos</li><li>Whether to save State to a server</li><li>Both default to no. Say nothing and it skips them</li></ul>                                                                                                                               |

### What it Writes

For a new Grid it writes these files in the framework's source folder, and adds the packages to `package.json`:

`columnDefs.ts`, `rowData.ts`, `adaptableOptions.ts`, `gridOptions.ts`, `agGridModules.ts`, `licenses.ts`, `onAdaptableReady.ts` and `styles.css`

If the project has no AGENTS.md block yet, it writes that too

For an existing Grid it edits the files you already have.

- Licence keys go in environment variables, not in the source

<!-- framework: vanilla,react,vue -->
### Vanilla / React / Vue

- In a Vite project those are `VITE_ADAPTABLE_LICENSE_KEY` and `VITE_AG_GRID_LICENSE_KEY`

<!-- /framework -->
<!-- framework: angular -->
### Angular

- In Angular they are read from `src/environments/environment.ts`. The file the Skill writes names them

<!-- /framework -->

### What it Runs

The Agent will run various tasks as part of its operation.

You do not run these - the agent does.

`detect`, `compat`, `scaffold`, `convert coldefs`, `docs get`, `docs demo`, `check setup` and `check state`.

With the app running, it reads the page: `listInstances()`, `getGridInfo()` and `getLogs()`.

If it cannot open the page, it asks you to paste those three calls into the browser console and paste the results back.

### When it is Finished

When the Skill is complete, the app builds and runs.

One AdapTable Grid is on screen, with no AdapTable errors. A licence warning in the console is expected until real keys are set.

You know where the keys and the State live.

### Taking a look inside the Skill

After you install the Skill, `adaptable-setup` looks like this:

```text
adaptable-setup/
├── SKILL.md                  # description + procedure
├── VERSION.md                # the version checked against /.well-known/skills/VERSION
└── references/
    ├── paths.md              # where the files go per framework
    └── _shared/              # the same in every Skill
        ├── grounding.md
        ├── docs-protocol.md
        ├── validation-loop.md
        ├── conversation.md
        ├── guards.md
        ├── capabilities.md
        └── agents-snippet.md
```

## Examples

### Create Grid From Spreadsheet

<SkillSteps title="A trade blotter from a spreadsheet" defaultExpanded="true" narrow="true">

<AiSkill skill="adaptable-setup" embedded>

<!-- framework: vanilla -->
### Vanilla

Create a TypeScript trade blotter from `data/trades.xlsx` with AdapTable
<!-- /framework -->
<!-- framework: react -->
### React

Create a React trade blotter from `data/trades.xlsx` with AdapTable
<!-- /framework -->
<!-- framework: angular -->
### Angular

Create an Angular trade blotter from `data/trades.xlsx` with AdapTable
<!-- /framework -->
<!-- framework: vue -->
### Vue

Create a Vue trade blotter from `data/trades.xlsx` with AdapTable
<!-- /framework -->

</AiSkill>

- Looks at the project: the framework, whether AG Grid is present, and which AdapTable & AG Grid versions match

<!-- framework: vanilla -->
### Vanilla

- If there is no project yet, it creates a fresh TypeScript project first

<!-- /framework -->
<!-- framework: react -->
### React

- If there is no project yet, it creates a fresh React project first

<!-- /framework -->
<!-- framework: angular -->
### Angular

- If there is no project yet, it creates a fresh Angular project first

<!-- /framework -->
<!-- framework: vue -->
### Vue

- If there is no project yet, it creates a fresh Vue project first

<!-- /framework -->

- Asks you once for what it needs — the AdapTable and AG Grid licence keys (or trial placeholders)
- Puts the keys in environment variables, never in source code
- Reads spreadsheet and shows you columns, their types and column it chose as primary; you confirm or correct
- Writes the AdapTable files: column definitions, row data, Adaptable Options and a minimal Initial State with one Layout and a Dashboard, with matching AdapTable and AG Grid versions
- Builds the app, runs it and looks at the page: one Grid, no AdapTable errors

- A running app with your data in an AdapTable Grid
- A short summary: where the Options and the Initial State live, which environment variables hold the keys, and that user changes are saved in the browser by default.
- Extras from the docs demos, and saving State to a server, are offered but not added unless you say so.

The CLI's `check setup` and `check state` report nothing, the build passes, and the running page shows one AdapTable instance with no errors in its logs.

</SkillSteps>

### Create Framework-Ready Grid

<!-- framework: vanilla -->
### Vanilla

<SkillSteps title="A new TypeScript project" narrow="true" defaultExpanded="true">

<AiSkill skill="adaptable-setup" embedded>

Set up a new TypeScript project with AdapTable and demo data

</AiSkill>

- creates the TypeScript project
- adds AdapTable with a demo dataset
- checks that it builds and the Grid mounts

The wiring lands in `src/main.ts`, through `Adaptable.init`.

A new app that you can now enhance and develop further

</SkillSteps>

<!-- /framework -->

<!-- framework: react -->
### React

<SkillSteps title="A new React project" narrow="true">

<AiSkill skill="adaptable-setup" embedded>

Set up a new React project with AdapTable and demo data

</AiSkill>

- creates the React project
- adds AdapTable with a demo dataset
- checks that it builds and the Grid mounts

The wiring lands in `src/App.tsx`, through `@adaptabletools/adaptable-react-aggrid`.

A new app that you can now enhance and develop further

</SkillSteps>

<!-- /framework -->

<!-- framework: angular -->
### Angular

<SkillSteps title="A new Angular project" narrow="true">

<AiSkill skill="adaptable-setup" embedded>

Set up a new Angular project with AdapTable and demo data

</AiSkill>

- creates the Angular project
- adds AdapTable with a demo dataset
- checks that it builds and the Grid mounts

The wiring lands in the root component, through `@adaptabletools/adaptable-angular-aggrid`.

A new app that you can now enhance and develop further

</SkillSteps>

<!-- /framework -->

<!-- framework: vue -->
### Vue

<SkillSteps title="A new Vue project" narrow="true">

<AiSkill skill="adaptable-setup" embedded>

Set up a new Vue project with AdapTable and demo data

</AiSkill>

- creates the Vue project
- adds AdapTable with a demo dataset
- checks that it builds and the Grid mounts

The wiring lands in `src/App.vue`, through `@adaptabletools/adaptable-vue-aggrid`.

A new app that you can now enhance and develop further

</SkillSteps>

<!-- /framework -->

### Add AdapTable to AG Grid

<SkillSteps title="AdapTable onto an existing AG Grid app" narrow="true" defaultExpanded="true">

<AiSkill skill="adaptable-setup" embedded>

Add AdapTable to this AG Grid app and move the column layout into an AdapTable Layout

</AiSkill>

<!-- framework: vanilla -->
### Vanilla

- `detect` finds a TypeScript app with AG Grid Enterprise and no AdapTable: path A. `compat` confirms the installed AG Grid matches the pairing and names the package, `@adaptabletools/adaptable`

<!-- /framework -->
<!-- framework: react -->
### React

- `detect` finds a React app with AG Grid Enterprise and no AdapTable: path A. `compat` confirms the installed AG Grid matches the pairing and names the wrapper, `@adaptabletools/adaptable-react-aggrid`

<!-- /framework -->
<!-- framework: angular -->
### Angular

- `detect` finds an Angular app with AG Grid Enterprise and no AdapTable: path A. `compat` confirms the installed AG Grid matches the pairing and names the wrapper, `@adaptabletools/adaptable-angular-aggrid`

<!-- /framework -->
<!-- framework: vue -->
### Vue

- `detect` finds a Vue app with AG Grid Enterprise and no AdapTable: path A. `compat` confirms the installed AG Grid matches the pairing and names the wrapper, `@adaptabletools/adaptable-vue-aggrid`

<!-- /framework -->

- Asks once for the licence keys (or trial placeholders) and writes them to the environment file

<!-- framework: vanilla -->
### Vanilla

- Reads `docs get getting-started-integration` for the installed major, adds `adaptableId` and `primaryKey`, creates the Grid with `Adaptable.init`, and moves the code that used the Grid API after creation into the `AdaptableReady` handler

<!-- /framework -->
<!-- framework: react -->
### React

- Reads `docs get react-integration` for the installed major, adds `adaptableId` and `primaryKey`, hands Grid creation to the wrapper, and moves the code that used the Grid API after creation into `onAdaptableReady`

<!-- /framework -->
<!-- framework: angular -->
### Angular

- Reads `docs get angular-integration` for the installed major, adds `adaptableId` and `primaryKey`, hands Grid creation to the wrapper, and moves the code that used the Grid API after creation into `adaptableReady`

<!-- /framework -->
<!-- framework: vue -->
### Vue

- Reads `docs get vue-integration` for the installed major, adds `adaptableId` and `primaryKey`, hands Grid creation to the wrapper, and moves the code that used the Grid API after creation into `onAdaptableReady`

<!-- /framework -->

- `convert coldefs src/columnDefs.ts` returns a Layout (order, hidden columns, widths, pinning, sorts, row groups), the ColDef properties to remove with their `file:line`, and the styling candidates.
- Asks: move all the Layout-owned properties (default yes)? Re-express the candidates now (default no)?
- Applies the agreed edits, runs `check setup` and `check state` until clean, builds, starts the dev server and reads the page: one instance, no AdapTable errors

- The same Grid, now created through AdapTable
- The layout in an Initial State Layout instead of the ColDefs
- A summary of where everything lives

</SkillSteps>