# Usage with npm

## Installing Pushwoosh Web Push SDK via npm

Here's how to install and use the Pushwoosh Web Push Notifications SDK in your project using npm.
This guide assumes you have a basic understanding of npm and JavaScript module imports.

### Install the SDK:

```bash title="Install Pushwoosh Web Push Notifications SDK"
npm install web-push-notifications
```

<Aside type="caution" title="Important Note on SDK Versioning (v3.45.0+)">
  Starting from version **3.45.0**, the Pushwoosh Web SDK introduced a modular approach for importing the core SDK and its UI widgets.

  - **Separate Imports:** You now need to import the main `Pushwoosh` class and any desired widgets (like `PWSubscriptionButtonWidget`, `PWSubscribePopupWidget`, etc.) separately. Prior to this version, all components were typically bundled into a single import.
  - **ES2020 Compilation:** The SDK is compiled to the ES2020 JavaScript specification from this version onwards. Please ensure your build environment and target browsers support ES2020 features.
</Aside>

### Service Worker Setup

When using the SDK via npm, the service worker file is located at:

```
node_modules/web-push-notifications/service-worker.js
```

**Important:** During your build or deployment process, you must copy this service worker file to the root of your website. This is crucial for push notifications to work correctly.

For example, in a webpack project, you can use `copy-webpack-plugin`:

```javascript
const CopyWebpackPlugin = require('copy-webpack-plugin');

module.exports = {
  // ...other webpack config
  plugins: [
    new CopyWebpackPlugin({
      patterns: [
        {
          from: 'node_modules/web-push-notifications/service-worker.js',
          to: 'service-worker.js' // Copies to output directory root
        }
      ]
    })
  ]
};
```

If you're using Vite, you can use the `vite-plugin-static-copy` plugin:


```javascript
// vite.config.js
import { defineConfig } from 'vite';
import { viteStaticCopy } from 'vite-plugin-static-copy'

export default defineConfig({
  // ...other vite config
  plugins: [
    // ...other plugins
    viteStaticCopy({
      targets: [
        {
          src: 'node_modules/web-push-notifications/service-worker.js',
          dest: '' // Copies to build output root
        }
      ]
    })
  ]
});
```
For other build systems, use their respective file copying mechanisms to ensure the service worker is available at your website's root.

### Built-in Widgets

The Pushwoosh Web SDK comes with four built-in UI widgets to enhance user interaction and streamline the subscription process. While the `PWSubscriptionPromptWidget` is primarily configured through the Pushwoosh Control Panel and browser settings, the other three widgets (`PWSubscriptionButtonWidget`, `PWSubscribePopupWidget`, and `PWInboxWidget`) offer detailed configuration options directly within the `init` method of the SDK.

Here's an overview of each widget:

1.  **Subscription Prompt (`PWSubscriptionPromptWidget`)**
This widget is responsible for displaying the browser's native prompt to ask users for permission to send push notifications. Its behavior is largely governed by browser standards and settings configured in your Pushwoosh Control Panel. It does not have specific configuration parameters within the `pushwoosh.push(['init', {...}])` call.

2.  **Subscription Button (`PWSubscriptionButtonWidget`)**
This widget adds a floating button (often a bell icon) to your site, allowing users to easily subscribe to or manage their notification preferences.
*   **Configuration:** Settings for this widget are managed under the `subscribeWidget` object in the `init` call.
*   **Learn more:** [Push Subscription Button](/developer/pushwoosh-sdk/web-push-notifications/push-subscription-button/)

3.  **Custom Subscription Popup (`PWSubscribePopupWidget`)**
A customizable pop-up that provides a more engaging way to ask for notification permissions before showing the native browser prompt.
*   **Configuration:** Customize its appearance and behavior using the `subscribePopup` object in the `init` call.
*   **Learn more:** [Custom Subscription Popup](/developer/pushwoosh-sdk/web-push-notifications/custom-subscription-popup/)

4.  **Inbox Widget (`PWInboxWidget`)**
This widget integrates an in-app message center, allowing users to view a history of rich push notifications.
*   **Configuration:** Managed via the `inboxWidget` object in the `init` call.
*   **Learn more:** [Web Inbox Widget](/developer/pushwoosh-sdk/web-push-notifications/web-inbox-widget/)

You can then initialize and run these widgets as shown in the examples below:

### Import and Initialize

```javascript title="Import and Initialize Pushwoosh"
import { Pushwoosh } from 'web-push-notifications';
import { PWSubscriptionPromptWidget } from 'web-push-notifications/widget-subscription-prompt';
import { PWSubscriptionButtonWidget } from 'web-push-notifications/widget-subscription-button';
import { PWSubscribePopupWidget } from 'web-push-notifications/widget-subscribe-popup';
import { PWInboxWidget } from 'web-push-notifications/widget-inbox';

const pushwoosh = new Pushwoosh();

pushwoosh.push(['init', {
  applicationCode: 'XXXXX-XXXXX', // your Pushwoosh Application Code
  apiToken: 'XXXXXXX', // Device API Token
  defaultNotificationTitle: 'Pushwoosh',
  defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png',
  serviceWorkerUrl: '/service-worker.js', // path to your copied service worker

  // Custom Subscription Popup settings
  subscribePopup: {
    enable: true // Enable the subscription popup
    // other options can be added here
  },

  // Push subscription button settings
  subscribeWidget: {
    enable: true // Enable the subscription button widget
    // other options can be added here
  },

  // Inbox widget settings
  inboxWidget: {
    enable: true // Enable the inbox widget
    // other options can be added here
  }
}]);

pushwoosh.push(async () => {
  try {
    const widget = new PWSubscriptionPromptWidget(pushwoosh);
    await widget.run();
  } catch (error) {
    console.error('PWSubscriptionPromptWidget initialization failed:', error);
  }
});

pushwoosh.push(async () => {
  try {
    const widget = new PWSubscriptionButtonWidget(pushwoosh);
    await widget.run();
  } catch (error) {
    console.error('PWSubscriptionButtonWidget initialization failed:', error);
  }
});

pushwoosh.push(async () => {
  try {
    const widget = new PWSubscribePopupWidget(pushwoosh);
    await widget.run();
  } catch (error) {
    console.error('PWSubscribePopupWidget initialization failed:', error);
  }
});

pushwoosh.push(async () => {
  try {
    const widget = new PWInboxWidget(pushwoosh);
    await widget.run();
  } catch (error) {
    console.error('PWInboxWidget initialization failed:', error);
  }
});
```

## Links

See an example application with React and Vite: https://github.com/Pushwoosh/websdk-npm-vite-react-example