GeoStyler

Common errors

• Error: Cannot find module 'react' or 'react-dom'

  cause Missing peer dependencies required by GeoStyler's React components.
  fix Install 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

  cause Attempting to import a default export (like `SLDParser`) as a named export from a CommonJS context, or incorrect bundling of ESM default exports.
  fix Ensure 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.

  cause The project's `node` engine requirement is not met, leading to runtime errors.
  fix Update 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'.

  cause TypeScript error indicating that a prop like `sldParser` is not recognized by the `Style` component's prop types.
  fix Ensure 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.

Warnings

• breaking GeoStyler 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.
  Fix: Review your build pipeline configuration (e.g., Webpack, Vite) for any LESS-related loaders or plugins and remove/update them to align with plain CSS.
• breaking The `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.
  Fix: Update `onCloneRule` and `onRemoveRule` callbacks to accept a numeric index parameter instead of a `RuleRecord` object when interacting with the `RuleTable` component.
• breaking The `node` engine requirement for GeoStyler is `>=20.6.0`. Running the package with older Node.js versions may lead to unexpected errors or failures.
  Fix: Ensure 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.
• gotcha GeoStyler 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.
  Fix: Install all required peer dependencies using npm or yarn: `npm install react react-dom ol @types/react @types/react-dom`.
• gotcha GeoStyler 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.
  Fix: Install parsers as needed (e.g., `npm install geostyler-sld-parser`) and import them from their specific package paths: `import SLDParser from 'geostyler-sld-parser';`
• breaking Some 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.
  Fix: Ensure 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.

Install

• npm install geostyler npm
• yarn add geostyler yarn
• pnpm add geostyler pnpm

Imports

• Style
  wrong:

  import StyleEditor from 'geostyler';

  correct:

  import { Style } from 'geostyler';

  The primary UI component for a full-featured style editor is named `Style`, not `StyleEditor`. It is a named export.
• GeoStylerStyle
  wrong:

  import { GeoStylerStyle } from 'geostyler';

  correct:

  import { Style } from 'geostyler-style';

  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
  wrong:

  import { SLDParser } from 'geostyler';

  correct:

  import SLDParser from 'geostyler-sld-parser';

  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.

Quickstart

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;