npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

qgserde

v0.3.1

Published

Editable, information-preserving QGIS project XML for TypeScript

Readme

qgserde

Read, edit, and write QGIS project files in TypeScript.

qgserde turns .qgs XML into a typed object. Edit project settings, layers, fields, and the layer tree, then choose a QGIS 3 or 4 version when writing it back. Settings outside the typed API retain their values, structure, and order.

Documentation · Demo · API reference

Pre-release. The API may change before the first release.

Usage

import { parseQgs, serializeQgs } from "qgserde";

const project = parseQgs(qgsXml);
project.title = "Sapporo";
project.crs = { authId: "EPSG:4326" };

for (const layer of project.layers) {
  layer.opacity = 0.8;
  if (layer.type === "vector") {
    layer.labelsEnabled = true;
    for (const field of layer.fields) field.alias = field.name;
  }
}

const xml = serializeQgs(project, { version: "4.2" });

Input and output are strings. Your application reads and writes the files.

To start a new project:

import { createProject, serializeQgs } from "qgserde";

const project = createProject({ title: "Cities" });
project.crs = { authId: "EPSG:4326" };
project.layers.push({
  type: "vector",
  id: "qgserde_cities_001",
  name: "Cities",
  provider: "ogr",
  source: "./cities.gpkg|layername=cities",
  crs: { authId: "EPSG:4326" },
  fields: [],
});

const qgis3Xml = serializeQgs(project, { version: "3.44" });
const qgis4Xml = serializeQgs(project, { version: "4.2" });

createProject() also works without arguments and defaults to an empty title. Use parseQgs(xml) to load an existing project, then edit its properties.

API

| Export | Purpose | | ------------------------------------ | --------------------------------------------------------------------- | | parseQgs(xml) | Read QGS XML into a QgsProject. | | createProject(options?) | Create an empty project with an optional title. | | serializeQgs(project, { version }) | Write a model for a QGIS 3 or 4 version. | | serializeJson(project) | Store a model as JSON tagged with the qgserde version. | | parseJson(json) | Restore a model stored by serializeJson. | | parseQgisVersion(value) | Split a QGIS version into numeric parts and an optional release name. | | QgsError | Identify failures by their code. |

The model contains plain objects and arrays. QgsMapLayer is a discriminated union: checking layer.type gives access to vector fields and renderers, raster bands, or the common settings of other layer types. Vector renderers, labeling, and layout items are modeled with their symbols, text formats, and settings; see the guide for the full coverage. See the guide for editing rules and the full type reference.

Data preservation

A parsed model stores known settings in typed properties. XML a layer's model does not cover is kept in its unmodeled property as plain, editable data; other objects still use internal extensions. The model does not keep the original XML string or a complete XML tree as a backup.

Known settings are always reconstructed from the model, including when unchanged. Parsed, JSON-restored, and new models use the same validation and output rules. Missing format metadata and redundant settings are normalized. Unknown elements, attributes, namespaces, comments, CDATA, and their placement are preserved. Numeric spelling, quotes, entity syntax, and the order of <maplayer> children (written as the target QGIS writes them) can change. Operations that would erase unknown nested data or collapse distinct view settings fail with INVALID_EDIT.

When a CRS contains only an authority ID, serialization adds a missing srsid lookup marker so QGIS can resolve it, including for CRS read from XML. Existing IDs, WKT and PROJ definitions are preserved as modeled values. User-defined (USER:) IDs are not completed; serializing one without WKT or PROJ causes INVALID_EDIT.

Models can be stored with serializeJson and restored with parseJson. The JSON records the qgserde version that wrote it; parseJson rejects JSON from an incompatible version (a different major, or a different minor before 1.0) with INVALID_VERSION, because the internal extensions format may change between them. Serialization leaves the model unchanged, so it can be written repeatedly for different target versions.

Known format differences are handled by the codec. Plugin settings, symbol details, and other unmodeled features are preserved without version conversion. The target QGIS installation must support those features.

Scope

  • QGS XML only. QGZ archives, QGD databases, attachments, and geographic data are outside the library's scope.
  • File paths and data source URIs are kept as supplied. qgserde does not check whether a source exists or rewrite paths for a new project location.
  • Layer IDs are read-only: tree, drawing-order, relation, join, layout, and plugin references use them. A layer with another ID is another layer.
  • Layer IDs must contain at least 11 UTF-16 code units. QGIS replaces shorter IDs on load, breaking tree and drawing-order references. Serialization rejects shorter IDs with INVALID_EDIT, including unchanged IDs read from XML. This constraint applies to every layer provider.
  • XML 1.0 only. External DTDs are never fetched. Internal DTD subsets, custom entities, cycles, and XML deeper than 512 levels are rejected.
  • ESM. Node.js 24.22.1+ or 26.12.1+ within those LTS lines; browser use requires a bundler and structuredClone. The library itself uses no Node.js APIs or browser DOM.

Development

See CONTRIBUTING.md for setup, documentation builds, and QGIS integration tests. CI runs on Node.js 24 and 26 and opens generated projects in QGIS 3.44, 4.0, and 4.2.

License

qgserde is licensed under the GNU Affero General Public License, version 3 or any later version (AGPL-3.0-or-later).

Third-party material retains its original license. Fixture sources and their licenses are listed in test/fixtures/README.md.