{"id":13222,"library":"geostyler-qgis-parser","title":"GeoStyler QGIS Parser","description":"The `geostyler-qgis-parser` package provides a GeoStyler Style Parser implementation specifically for QGIS (QML) styles. It enables the conversion of QGIS native styling information into the GeoStyler internal style format and vice-versa, facilitating interoperability between QGIS and other mapping libraries or services supported by GeoStyler. The current stable version is 4.1.0, released in November 2025. The project demonstrates an active release cadence with several patch and minor updates throughout 2025, indicating ongoing development and maintenance. Key differentiators include its tight integration with the GeoStyler ecosystem and its ability to handle specific QGIS style properties like `fontweight`, `fontItalic`, and `PointPat` support, as noted in recent updates. This parser is crucial for applications that need to manage or display geospatial data styled originally in QGIS.","status":"active","version":"4.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/geostyler/geostyler-qgis-parser","tags":["javascript","geostyler","parser","style","qgis","qml","typescript"],"install":[{"cmd":"npm install geostyler-qgis-parser","lang":"bash","label":"npm"},{"cmd":"yarn add geostyler-qgis-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add geostyler-qgis-parser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency defining the GeoStyler internal style format for conversion. All GeoStyler parsers rely on this common interface.","package":"geostyler-style","optional":false},{"reason":"Used for parsing and writing CQL (Common Query Language) filter expressions, which are often embedded within QGIS styles.","package":"geostyler-cql-parser","optional":false},{"reason":"Runtime dependency for parsing QGIS XML (.qml) style files.","package":"@xmldom/xmldom","optional":false},{"reason":"Provides polyfills for ECMAScript features, ensuring broader compatibility across different JavaScript environments.","package":"core-js","optional":false}],"imports":[{"note":"The package switched to ESM (ECMAScript Modules) only since v3.0.0. CommonJS `require` statements are no longer supported.","wrong":"const QGISStyleParser = require('geostyler-qgis-parser');","symbol":"QGISStyleParser","correct":"import { QGISStyleParser } from 'geostyler-qgis-parser';"},{"note":"Importing GeoStyler's `Style` type for type safety when working with the parsed or generated style objects.","symbol":"Style","correct":"import type { Style } from 'geostyler-style';"},{"note":"For advanced use cases or introspection, you might need internal types representing the raw QGIS style structure, though direct manipulation is generally not recommended for users. The exact path may vary slightly with minor versions.","symbol":"QgsStyle","correct":"import type { QgsStyle } from 'geostyler-qgis-parser/dist/types/qgs-classes';"}],"quickstart":{"code":"import { QGISStyleParser } from 'geostyler-qgis-parser';\nimport type { Style } from 'geostyler-style';\n\n// A minimal QML string representing a simple red fill style\nconst qmlString = `\\n\\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n`;\n\nconst parser = new QGISStyleParser();\n\nasync function convertStyle() {\n try {\n // Parse QML to GeoStyler Style\n const { output: geoStylerStyle, errors: readErrors } = await parser.readStyle(qmlString);\n if (readErrors.length > 0) {\n console.warn('Errors during QML parsing:', readErrors);\n }\n console.log('Parsed GeoStyler Style:', JSON.stringify(geoStylerStyle, null, 2));\n\n // Example: Modify the style (e.g., change fill color to blue)\n if (geoStylerStyle && geoStylerStyle.rules && geoStylerStyle.rules.length > 0) {\n const rule = geoStylerStyle.rules[0];\n if (rule.symbolizers && rule.symbolizers.length > 0 && rule.symbolizers[0].kind === 'Fill') {\n rule.symbolizers[0].color = '#0000FF'; // Change to blue\n }\n }\n\n // Write the modified GeoStyler Style back to QML\n const { output: newQmlString, errors: writeErrors } = await parser.writeStyle(geoStylerStyle as Style);\n if (writeErrors.length > 0) {\n console.warn('Errors during QML writing:', writeErrors);\n }\n console.log('Converted QML String (blue fill):', newQmlString);\n } catch (error) {\n console.error('An error occurred during style conversion:', error);\n }\n}\n\nconvertStyle();","lang":"typescript","description":"Demonstrates how to instantiate the `QGISStyleParser`, read a QML string into a GeoStyler Style object, modify the style, and then write the GeoStyler Style back to a QML string."},"warnings":[{"fix":"Migrate your project to use ES modules (`import`/`export`) or use a bundler (like Webpack, Rollup, Parcel, Vite) that transpiles ESM to CommonJS if backward compatibility is strictly required. Ensure your `package.json` specifies `\"type\": \"module\"` for direct Node.js execution of ESM.","message":"Version 3.0.0 switched the package build to ESM (ECMAScript Modules) only. CommonJS `require()` statements will fail, leading to `TypeError: QGISStyleParser is not a constructor` or similar import errors in Node.js environments.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure that all GeoStyler-related dependencies, especially `geostyler-style`, are updated to compatible versions. If using `geostyler-qgis-parser` v2.x, ensure `geostyler-style` is at least `^7.0.0`. For v3.x and above, refer to `geostyler-qgis-parser`'s `package.json` for the exact `geostyler-style` peer dependency.","message":"Version 2.0.0 introduced a significant breaking change: the parser now strictly expects and outputs GeoStyler styles compliant with `geostyler-style` version 7. Older GeoStyler styles (pre-v7) or those from other parsers relying on older `geostyler-style` versions may not be compatible, leading to parsing errors or incorrect conversions.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"Test conversion results thoroughly with your target QGIS version. If interoperability with older QGIS versions (pre-3.28) is critical, you might need to use an older version of `geostyler-qgis-parser` or manually adjust the output QML for compatibility, though the latter is complex.","message":"Version 4.0.0 updated the `QGISStyleParser` to output QGIS 3.28 compliant QML styles. While this improves compatibility with newer QGIS versions, it may cause issues or unexpected behavior when interacting with older QGIS installations or systems expecting older QML formats.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade to `geostyler-qgis-parser` version 4.1.0 or newer to ensure full support for these QGIS style features. If upgrading is not possible, be aware that these properties will be dropped or ignored during style parsing and writing.","message":"Support for `fontweight`, `fontItalic` style properties, and `PointPat` symbols was added in version 4.1.0. Older versions of the parser will not correctly interpret or write these specific QGIS style properties, potentially losing styling information during conversion.","severity":"gotcha","affected_versions":"<4.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update your import statement to use ES module syntax: `import { QGISStyleParser } from 'geostyler-qgis-parser';`. If running in Node.js, ensure your environment supports ESM (e.g., by setting `\"type\": \"module\"` in `package.json` or using `.mjs` file extensions).","cause":"Attempting to use `require()` to import `QGISStyleParser` in a CommonJS environment after the package switched to ESM only in v3.0.0.","error":"TypeError: QGISStyleParser is not a constructor"},{"fix":"Update `geostyler-style` to the version specified as a peer dependency by your `geostyler-qgis-parser` version. Also, ensure any GeoStyler style objects passed to the parser are generated by compatible GeoStyler components or parsers.","cause":"The `geostyler-qgis-parser` expects a specific version of the `geostyler-style` format. This error indicates a mismatch between the input GeoStyler style object's version and what the parser expects, often due to an outdated `geostyler-style` dependency or style object from another parser.","error":"Error: Invalid GeoStyler style format detected. Expected GeoStyler Style version X, got version Y."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}