Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Style
✓ import { Style } from 'geostyler';
✗ import StyleEditor from 'geostyler';
The primary UI component for a full-featured style editor is named `Style`, not `StyleEditor`. It is a named export.
GeoStylerStyle
✓ import { Style } from 'geostyler-style';
✗ import { GeoStylerStyle } from 'geostyler';
The core type definition for a GeoStyler style is `Style` and is typically imported from the `geostyler-style` package, which is a dependency of `geostyler`.
SLDParser
✓ import SLDParser from 'geostyler-sld-parser';
✗ import { SLDParser } from 'geostyler';
Parsers for specific styling formats (like SLD) are provided as separate 'micro packages' and are default exports from their respective libraries, not from the main `geostyler` package.
This quickstart demonstrates a basic GeoStyler `Style` (the main UI component) integrated into a React application, allowing users to view and edit a geospatial style. It initializes a simple point style, handles style changes, and shows how to pass parser instances to the `Style` component.
import React, { useState } from 'react';
import { Style } from 'geostyler';
import SLDParser from 'geostyler-sld-parser';
import OpenLayersParser from 'geostyler-openlayers-parser';
import { Style as GeoStylerCoreStyle } from 'geostyler-style';
const initialGeoStylerStyle: GeoStylerCoreStyle = {
name: 'My Initial Style',
rules: [
{
name: 'Orange Point Rule',
symbolizers: [
{ kind: 'Mark', wellKnownName: 'circle', color: '#FFA500', radius: 8 }
],
},
],
};
const MyStyleEditor: React.FC = () => {
const [currentStyle, setCurrentStyle] = useState<GeoStylerCoreStyle>(initialGeoStylerStyle);
const sldParser = new SLDParser();
const olParser = new OpenLayersParser();
// Note: For a fully functional setup, you might need to provide a data source
// and more comprehensive locale and editor configurations via the Style component's props.
// This example focuses on basic style management.
return (
<div style={{ width: '100%', height: 'calc(100vh - 20px)', padding: '10px' }}>
<h1>GeoStyler Style Editor</h1>
<Style
style={currentStyle}
onStyleChange={(newStyle: GeoStylerCoreStyle) => {
console.log('Style changed:', newStyle);
setCurrentStyle(newStyle);
}}
// The Style component often needs parsers to function correctly,
// enabling read/write operations for different formats.
sldParser={sldParser}
olParser={olParser}
// Other parsers can be added as props: qmlParser, mapboxStyleParser, etc.
// locale={{ /* custom locale */ }}
// data={{ /* data source */ }}
/>
<pre style={{ marginTop: '20px', backgroundColor: '#eee', padding: '10px' }}>
{JSON.stringify(currentStyle, null, 2)}
</pre>
</div>
);
};
export default MyStyleEditor;
Debug
Known issues
breakingGeoStyler updated its internal styling from LESS to plain CSS. If your application's build configuration previously assumed the existence of `.less` files or specific LESS tooling, you might need to adjust these configurations.fixReview your build pipeline configuration (e.g., Webpack, Vite) for any LESS-related loaders or plugins and remove/update them to align with plain CSS.
affects: >=17.0.0
breakingThe `RuleTable` component's `onCloneRule` and `onRemoveRule` signatures changed. They now expect a numeric index instead of a `RuleRecord`. This impacts applications explicitly using `RuleTable` or interacting with these callbacks.fixUpdate `onCloneRule` and `onRemoveRule` callbacks to accept a numeric index parameter instead of a `RuleRecord` object when interacting with the `RuleTable` component.
affects: >=17.0.0
breakingThe `node` engine requirement for GeoStyler is `>=20.6.0`. Running the package with older Node.js versions may lead to unexpected errors or failures.fixEnsure your development and deployment environments are running Node.js version 20.6.0 or higher. Update Node.js using `nvm` or your preferred package manager.
affects: >=18.0.0
gotchaGeoStyler relies on several peer dependencies, including `react`, `react-dom`, and `ol` (OpenLayers). These must be installed separately in your project, along with their respective `@types` packages for TypeScript.fixInstall all required peer dependencies using npm or yarn: `npm install react react-dom ol @types/react @types/react-dom`.
affects: All versions
gotchaGeoStyler emphasizes a 'micro packages' approach. Style parsers (e.g., `geostyler-sld-parser`, `geostyler-openlayers-parser`) are separate npm packages and must be installed and imported individually, not directly from the main `geostyler` package.fixInstall parsers as needed (e.g., `npm install geostyler-sld-parser`) and import them from their specific package paths: `import SLDParser from 'geostyler-sld-parser';`
affects: All versions
breakingSome parser packages (e.g., `geostyler-geojson-parser`) have introduced ESM builds as a breaking change, requiring adaptation of import paths and/or configurations if your application was relying on CommonJS or older module resolution.fixEnsure your project is configured to handle ESM imports, potentially updating bundler configurations or import statements to include `.js` extensions for ESM modules as necessary. This change affects specific parser packages, not the main `geostyler` package directly.
affects: >=2.0.0 (for geostyler-geojson-parser)
Errors
Common errors & fixes
Error: Cannot find module 'react' or 'react-dom'
Missing peer dependencies required by GeoStyler's React components.
fixInstall React and ReactDOM: `npm install react react-dom` along with their types if using TypeScript: `npm install @types/react @types/react-dom`.
TypeError: (0 , geostyler_sld_parser__WEBPACK_IMPORTED_MODULE_2__.default) is not a constructor
Attempting to import a default export (like `SLDParser`) as a named export from a CommonJS context, or incorrect bundling of ESM default exports.
fixEnsure you are using correct ESM `import SLDParser from 'geostyler-sld-parser';` and that your build tool is correctly configured for ESM. If in a strict CJS environment, you might need `const SLDParser = require('geostyler-sld-parser').default;` or similar, though ESM is preferred. ERR_OS_NOT_SUPPORTED: The current Node.js version is not supported. Please use Node.js >= 20.6.0.
The project's `node` engine requirement is not met, leading to runtime errors.
fixUpdate your Node.js installation to version 20.6.0 or newer. Use `nvm install 20 && nvm use 20` or a similar method appropriate for your system.
Property 'sldParser' does not exist on type 'IntrinsicAttributes & StyleProps'.
TypeScript error indicating that a prop like `sldParser` is not recognized by the `Style` component's prop types.
fixEnsure all required parser packages are correctly installed and that the `Style` component in your `geostyler` version supports these specific parser props. If types are outdated, consider `npm update` or checking the documentation for prop name changes.
Audit
Dependencies
reactrequiredRequired for GeoStyler's UI components, as it is a React component library.
react-domrequiredRequired for rendering GeoStyler's React UI components to the DOM.
olrequiredPeer dependency for OpenLayers integration, particularly for the OpenLayers parser and related components. GeoStyler UI can connect to several data sources.
@types/reactoptionalTypeScript type definitions for React, essential when using GeoStyler with TypeScript.
@types/react-domoptionalTypeScript type definitions for ReactDOM, essential when using GeoStyler with TypeScript.