# @nextgis/ngw-connector

> A lightweight HTTP client optimized for use with NextGIS Web API

Latest version **4.1.1** (published 2026-11-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install @nextgis/ngw-connector
pnpm add @nextgis/ngw-connector
yarn add @nextgis/ngw-connector
bun add @nextgis/ngw-connector
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.1.1 |
| Published | 2026-11-13 |
| First published | 2018-10-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.20.4 |
| Dependencies | 6 |
| Unpacked size | 1.2 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 31 |
| Author | NextGIS |
| Maintainers | rendrom, maximdubinin, karavanjo |
| Keywords | NextGIS, MAP |

## Links

- npm: https://www.npmjs.com/package/@nextgis/ngw-connector
- Repository: https://github.com/nextgis/nextgis_frontend
- Homepage: https://github.com/nextgis/nextgis_frontend/tree/master/packages/ngw-connector#readme
- npm.io page: https://npm.io/package/@nextgis/ngw-connector

## Dependencies (6)

- [events](https://npm.io/package/events.md) *
- [form-data](https://npm.io/package/form-data.md) ^4.0.6
- [@types/events](https://npm.io/package/@types/events.md) ^3.0.0
- [@nextgis/cache](https://npm.io/package/@nextgis/cache.md) 4.1.1
- [@nextgis/utils](https://npm.io/package/@nextgis/utils.md) 4.1.1
- [@nextgis/cancelable-promise](https://npm.io/package/@nextgis/cancelable-promise.md) 4.0.2

## Recent versions

- 4.1.1 (latest) — 2026-11-13
- 4.0.2 — 2026-11-05
- 2.5.5 — 2026-11-02
- 3.1.1 — 2026-11-02
- 4.0.1 — 2026-11-02
- 4.0.0 — 2026-08-30
- 4.0.0-rc.2 — 2026-08-30
- 4.0.0-rc.1 — 2026-08-29
- 4.0.0-rc.0 — 2026-08-27
- 4.0.0-alpha.8 — 2026-08-25
- 4.0.0-alpha.6 — 2026-08-24
- 4.0.0-alpha.5 — 2026-08-21
- 4.0.0-alpha.2 — 2026-05-28
- 3.0.1 — 2025-07-28
- 3.0.0 — 2025-07-26
- … 204 more at https://npm.io/package/@nextgis/ngw-connector/versions

## README

# NgwConnector

![version](https://img.shields.io/npm/v/@nextgis/ngw-connector)

A lightweight HTTP client optimized for use with [NextGIS Web](http://docs.nextgis.com/docs_ngweb_dev/doc/developer/toc.html) API.

Use this package when an application needs NextGIS Web resources, features, or
other HTTP API operations without a map. Ready-to-use `ngw-*` map packages
expose an initialized connector as `ngwMap.connector`.

> [!IMPORTANT]
> The typed `NgwConnector.route()` API requires declarations generated for your NextGIS Web deployment. Install `@nextgis/ngw-types-loader` and run it before using `route()`. The declarations depend on the components and extensions installed on that server.
>
> ```bash
> npx @nextgis/ngw-types-loader https://your-ngw-server.com
> ```
>
> See the [NGW Types Loader documentation](https://github.com/nextgis/nextgis_frontend/tree/master/packages/ngw-types-loader#readme) for detailed instructions.

Make sure CORS is registered in the [NextGIS Web settings](https://docs.nextgis.com/docs_ngcom/source/CORS.html) to be able to send requests.

## Installation

### In Browser

#### Include assets

Simply download and include with a script tag, `NgwConnector` will be registered as a global variable.

```html
<script src="../lib/ngw-connector.global.js"></script>

<script>
  var ngwConnector = new NgwConnector({
    baseUrl: 'https://demo.nextgis.com',
  });
</script>
```

#### CDN

unpkg

```html
<script src="https://unpkg.com/@nextgis/ngw-connector"></script>
```

jsdelivr

```html
<script src="https://cdn.jsdelivr.net/npm/@nextgis/ngw-connector"></script>
```

We recommend linking to a specific version number `/ngw-connector@[version]`

### In Node.js

```bash
npm install @nextgis/ngw-connector
```

## TypeScript Support

`NgwConnector.route()` uses declarations generated by NextGIS Web itself. Install the loader as a development dependency:

```bash
npm install --save-dev @nextgis/ngw-types-loader
```

Then generate types from the NextGIS Web deployment your application connects to:

```bash
npx @nextgis/ngw-types-loader https://your-ngw-server.com
```

If the URL is omitted, the loader uses `https://demo.nextgis.com`:

```bash
npx @nextgis/ngw-types-loader
```

The declarations are installed as resolvable packages under `node_modules/@nextgisweb`; no `tsconfig.json` changes are required. Run the loader again after changing the NextGIS Web version, components, or extensions.

For more details, refer to the [NGW Types Loader](https://www.npmjs.com/package/@nextgis/ngw-types-loader).

## Usage

```javascript
import NgwConnector from '@nextgis/ngw-connector';

const ngwConnector = new NgwConnector({
  baseUrl: 'https://demo.nextgis.com',
  // auth: {login, password}
});

ngwConnector
  .route('resource.item', { id: 485 })
  .get()
  .then((data) => {
    console.log(data);
  });

ngwConnector.route('resource.collection').patch({ json: RESOURCE });
ngwConnector.route('feature_layer.feature.collection', { id }).patch({
  json: ITEMS,
  query: {
    srs: 4326,
    geom_format: 'geojson',
  },
});
ngwConnector
  .route('feature_layer.feature.item', { id, fid })
  .put({ json: ITEM });
ngwConnector.route('feature_layer.feature.item', { id, fid }).delete();

// Shortcuts methods to find resources
ngwConnector.getResource(2011); // by id
ngwConnector.getResource('keyname'); // by keyname

ngwConnector.getResources({ cls: 'vector_layer', parent__id: 0 }); // find resources by partial resource params
ngwConnector.getResource({ display_name: 'My layer', parent__id: 0 }); // get first
```

## Typed routes and compatibility methods

Prefer `route()` for API endpoints represented by the declarations generated
by your NextGIS Web deployment. Route names, path parameters, query parameters,
and response bodies are derived from `@nextgisweb` modules.

Methods such as `getResource()` and `getResources()` use the compatibility
types shipped with `ngw-connector`. They remain useful for established code and
for operations without a generated route declaration. These two type sources
are intentionally separate because available server routes depend on installed
NextGIS Web components and extensions.

Check out the [API Documentation](https://code-api.nextgis.com/modules/_nextgis_ngw-connector.html)

## NGW API

[NextGIS Web API Doc](http://docs.nextgis.com/docs_ngweb_dev/doc/developer/toc.html)

```javascript
ngwConnector.get(request_name, request_options, arguments);
```

[request_options](https://code-api.nextgis.com/interfaces/ngw_connector.RequestOptions.html)

[API request names](https://demo.nextgis.com/doc/api)

See also the [package architecture guide](../../docs/PACKAGES.md).

## Commercial support

Need to fix a bug or add a feature to `@nextgis/ngw-connector`? We provide custom development and support for this software. [Contact us](http://nextgis.com/contact/) to discuss options!

[![http://nextgis.com](https://nextgis.com/img/nextgis.png)](http://nextgis.com)

---
_Source: https://npm.io/package/@nextgis/ngw-connector · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
