# @vercel/toolbar

Manually inject the Vercel toolbar on any site.

## Install

```sh
npm install @vercel/toolbar
```

## Usage

This library can be used with any framework

### Plain JS

```js
import { mountVercelToolbar } from '@vercel/toolbar';

if (userIsEmployee) {
  mountVercelToolbar();
}
```

### React

```js
import { mountVercelToolbar, unmountVercelToolbar } from '@vercel/toolbar';

function VercelToolbar() {
  const shouldInjectToolbar = useIsUserEmployee();

  useEffect(() => {
    if (shouldInjectToolbar) {
      // Returns a cleanup function to unmount the toolbar
      return mountVercelToolbar();
    }
  }, [shouldInjectToolbar]);

  return null;
}
```

### Next.js

For usage in Next.js, you can instead import the `VercelToolbar` component which will use [`next/script`](https://nextjs.org/docs/api-reference/next/script):

```js
import { VercelToolbar } from '@vercel/toolbar/next';

export default function MyApp({ Component, pageProps }) {
  const shouldInjectToolbar = useIsUserEmployee();

  return (
    <>
      <Component {...pageProps} />
      {shouldInjectToolbar && <VercelToolbar />}
    </>
  );
}
```

### Nuxt

For usage in Nuxt, you can install the Vercel toolbar as a module:

```sh
npx nuxt module add @vercel/toolbar
```

No other configuration is required &mdash; it should just work! ✨

## Usage in `localhost`

Allows you to view comments left in your preview deployment while developing locally.

Prerequisites:

- You have linked your project with the Vercel project via `vc link`
- You have checked out the same branch as the preview

Adjust the code above, to always inject the toolbar in development

```js
import { VercelToolbar } from '@vercel/toolbar/next';

export default function MyApp({ Component, pageProps }) {
  const isUserEmployee = useIsUserEmployee();
  const shouldInjectToolbar =
    process.env.NODE_ENV === 'development' || isUserEmployee;

  return (
    <>
      <Component {...pageProps} />
      {shouldInjectToolbar && <VercelToolbar />}
    </>
  );
}
```

Then, import and use the Next.js plugin in your `next.config.js`:

```js
// next.config.js
const withVercelToolbar = require('@vercel/toolbar/plugins/next')();

const nextConfig = {
  ...
}

module.exports = withVercelToolbar(nextConfig);
```

Now, when running `next dev` you will see the Vercel toolbar and will be able to authenticate and interact with all the comments left in the preview environment of that branch.

### Options

You can configure some options for the plugin by passing an object in like:

```js
const withVercelToolbar = require('@vercel/toolbar/plugins/next')({
  devServerPort: 3123,
  enableInProduction: false,
});
```

The available options are

#### `devServerPort?: number`

> Port on which the toolbar's dev server will run locally (defaults to `43214`)

The toolbar runs a server locally to check the local git branch and watch for it to change, so it can reload the page and show the correct comments view

#### `enableInProduction?: boolean`

> Defaults to `false`. If `true` the toolbar's dev server will run when `NODE_ENV === 'production'`.

## Docs

See the [documentation](https://vercel.com/docs/workflow-collaboration/comments/in-production-and-localhost) for more details.