# Common pitfalls and how to avoid them

These are real issues discovered during plugin development. Read before writing
plugin logic — each one will save you debugging time.

## Pitfall 1: Importing `@teable/*` packages instead of using host globals

```typescript
// WRONG — webpack externals map these away at build time, so at runtime
// the import produces `undefined` or throws:
import { useFields } from '@teable/sdk';        // → undefined at runtime
import { Button } from '@teable/ui-lib';        // → undefined at runtime
import { definePlugin } from '@teable/plugin-sdk'; // fine (it re-exports from host)

// CORRECT — always read from the host global:
const host = window.__TEABLE_HOST__;
const { useFields } = host.SDK;
const { Button } = host.UILib;
const { definePlugin } = host.PluginSDK;
const React = host.React;
```

The webpack `externals` config in the scaffold template maps `@teable/sdk` →
`window.__TEABLE_HOST__.SDK` at build time. This means the bundled code replaces
the import with `window.__TEABLE_HOST__.SDK`, but destructuring from the import
statement doesn't survive the webpack transformation — use direct `host.*`
access instead. The only exception is `@teable/plugin-sdk` which re-exports
from `window.__TEABLE_HOST__.PluginSDK` at the level webpack expects.

**Symptoms**: `useFields is not a function`, `Cannot read properties of undefined`,
or components silently rendering nothing.

## Pitfall 2: `window.__TEABLE_HOST__` is undefined

The host object is injected by `HostInitializer` which mounts inside
`<AppProvider>`. This happens after the initial React tree render. If you try
to access `window.__TEABLE_HOST__` in a script that executes before the host
tree mounts, it will be `undefined`.

**Fix**: The `PluginLoader` component ensures the host is ready before loading
plugin scripts, so plugins loaded through the normal flow don't hit this. But
if you're testing a plugin directly (e.g. loading main.js in a browser console),
you'll see `__TEABLE_HOST__` is null until the app renders.

## Pitfall 3: Upload returns 403 — not a developer

Only users in the `plugin_developer` DB table can upload bundles. The
`DeveloperGuard` checks this. If you get 403 on `upload-bundle`, your user is
not whitelisted.

**Fix**: Add the user to `plugin_developer`:

```sql
INSERT INTO plugin_developer (id, user_id, email, created_by)
VALUES (gen_random_uuid(), '<userId>', '<email>', '<adminUserId>');
```

## Pitfall 4: Enable (plugin-config) must be called before install

Installing a plugin to a position (contextMenu / panel / view / dashboard)
requires the plugin to be enabled first. If you skip enable and call install
directly, you'll get 403.

**The correct sequence is always**:
1. Upload bundle → get pluginId
2. Enable via `PUT /base/:baseId/plugin-config/:pluginId`
3. Install to position

## Pitfall 5: `getSelectionRecords` returns empty array, not throw

The old iframe/ZIP `bridge.getSelectionRecords()` threw when nothing was
selected. The dynamic system's `PluginSDK.getSelectionRecords()` returns an
empty array instead. You still need to handle the empty case in your UI,
but you don't need a try/catch wrapper.

```typescript
const { getSelectionRecords } = host.PluginSDK;
const res = await getSelectionRecords(tableId, viewId, selection);
if (res.records.length === 0) {
  // Show "no records selected" message — no try/catch needed
}
```

## Pitfall 6: Plugin component renders nothing / context menu empty

If your plugin uploads, enables, and installs successfully but the component
never appears:

1. **Check `plugin.json` `positions`** — it must include the position you're
   installing to (e.g. `"positions": ["contextMenu"]`)
2. **Check `onLoad` registration** — `ctx.addContextMenuAction('main', Component)`
   must be called inside `onLoad`
3. **Check Authority Matrix** — the user's role must have the plugin enabled
   in AM. For the test account, the owner bypasses AM, but for other users,
   an admin must enable the plugin per role in the RoleEditor UI.
4. **Check browser console** — errors in `onLoad` are silently caught; add a
   `console.log` at the top of `onLoad` to verify it runs.

## Pitfall 7: Component uses JSX but webpack doesn't transpile it

The scaffold template uses `ts-loader` with `jsx: "react-jsx"` in tsconfig.
If you're setting up the webpack config manually, make sure:
- `tsconfig.json` has `"jsx": "react-jsx"` under `compilerOptions`
- The plugin does NOT need `import React from 'react'` at the top when using
  `react-jsx` transform — JSX is auto-transpiled. But you still need
  `const React = host.React` for any explicit `React.createElement` calls.