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.
