Sentinel Hub custom scripts are eval scripts, not a plugin system

A custom script is server side JavaScript that the service executes for you

The core idea is stated plainly in the repository description of custom scripts. They are a piece of JavaScript code used to visualise satellite imagery and to control what values the Sentinel Hub services will return. Any visualisation of any constellation, for example a Sentinel-2 satellite, even a simple true colour composite, is dictated by a custom script. That last clause is the one that changes how you think about the product. A true colour composite is not a preset button in a user interface, it is something you express in code, and the service evaluates that code against the data it holds for your request. The scripts are fed to the services via the URL, so a script is a document you point an API call at rather than a library you install and import. The link to the evalscript documentation is the primary reference for how to write one, and the tutorial and official documentation are offered as further reading for the structure of a script.

The repository is grouped by datasource, and that grouping is the contract

The top level of the repository is an index of constellations and collections, and that structure is more than navigation. There are directories for sentinel-1, sentinel-2, sentinel-3, sentinel-5p, sentinel1-monthly-mosaic, sentinel2-120m-mosaic, sentinel2-quarterly-cloudless-mosaic, plus landsat-1-5-mss, landsat-4-5-tm, landsat-7-etm, landsat-8, copernicus_services, airbus_pleiades, airbus_spot, planet, dem, hls, other_collections, planetary-variables, data-fusion, EOB-layers and slstr, with matching markdown index files such as sentinel.md, landsat.md and airbus.md at the root. A script is not portable between these folders, because the bands, the resolution, the metadata and the processing parameters differ per datasource. When you add your own, the instructions are to copy the example directory to a directory based on the datasource you are publishing for, named after what the product is about, and to use snake_case if more than one word is used. That directory placement is what tells the service how to interpret the script.

A script directory is a README, a script.js and an index entry

The contribution format is small and worth copying if you build your own catalogue. Inside each script folder you implement the product in the script.js file, and the example folder includes an empty custom script with comments meant to help you build your own. Alongside that sits a README.md for the script, which the instructions say to fill in with details about the project, using the rest of the file as a template while removing the instructional chapter. Other README files demonstrate the range of formatting, with the Sentinel-2 cloud based detection example used as a reference for mathematical formulas and the NDVI uncertainty example as a reference for adding images. Finally, you add an entry pointing to your script in the top level markdown file for that datasource, for example sentinel-2.md, and a link and a short description will do. The visualisation of these scripts is published on a dedicated site, which is the same site the repository serves.

The docs site is a Jekyll site, and you can run it locally before opening a PR

Testing your changes locally is described as optional but it makes pull requests quicker to handle since they should have less mistakes. The procedure is based on testing a GitHub Pages site locally with Jekyll, and the repository already contains the pieces Jekyll expects, including a _config.yml file, _layouts/, _includes/, _sass/ and a Gemfile. On Linux you install ruby, then bundler, then create a Gemfile in the root folder where the _config.yml file is, with this content:

source 'https://rubygems.org'
gem "github-pages", "~> GH_VERSION", group: :jekyll_plugins
gem "just-the-docs"

The GH_VERSION placeholder is replaced with the version number displayed next to github-pages. On macOS the instructions install chruby, ruby-install and xz, install a specific ruby version with ruby-install, and wire chruby into the shell profile with these lines:

  echo "source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh" >> ~/.zshrc
  echo "source $(brew --prefix)/opt/chruby/share/chruby/auto.sh" >> ~/.zshrc
  echo "chruby ruby-3.1.3" >> ~/.zshrc # run 'chruby' to see actual version

After that, install jekyll with gem install jekyll and bundler with gem install bundler, run bundle install, add the missing webrick package with bundle add webrick, and then build the site with bundle exec jekyll serve. When that works, the site is visible on 127.0.0.1:4000, so you can see your script page rendered before anyone else does.

Forking is optional, and sending the folder is a valid path to publication

The contribution guidance is unusually accommodating about how you get the work in. You fork the repository to get your own copy, and it is easiest to fork on GitHub, but the instructions note that some people might not have a GitHub account or might not want to deal with versioning and collaboration tools, in which case you can download the whole repository as a Zip file and work from there. The same pragmatism shows up at the pull request step. If you feel overwhelmed by that step and would still like to contribute, you can send the folder you created and the maintainers will take care of it. The repository also carries a template at contribute/example showing how a script page can be structured, plus an AGENTS.md, a CLAUDE.md and a .gemini directory at the top level, which are the instruction files used by coding assistants when working in the tree.

A shared licence makes a forked catalogue a derivative work

The repository is licensed under CC-BY-SA-4.0, and that choice has a direct effect on what you can do with a script you did not write. Attribution and share alike are both required, so reusing a published script in a product of your own means crediting the author and licensing your derivative under the same terms. For a script repository of visualisation code, where the code is short and the attribution is easy to state, that is a workable arrangement. It does mean the licence is not permissive like MIT or Apache, so a team whose legal process assumes permissive code will need to look at it. The repository is not archived and the last push was on 2026-10-14, so it is being worked on, but it publishes no GitHub releases, which means the commit history is the version history. The published site, custom-scripts.sentinel-hub.com, is the place to see what is currently available.

Where the custom script approach is the wrong tool

The boundary is set by what the service will evaluate and what it will not. A custom script shapes processing and visualisation of data the Sentinel Hub services already hold, and it runs inside their environment. It is therefore the wrong tool for a task that needs your own network access, your own model inference, an arbitrary third party API call, or a computation over data the service does not have, since a script has no way to reach outside the processing environment. It is also the wrong choice for a bulk pipeline where you want to control scheduling, retries and cost, because the invocation model is a URL per request rather than a batch job you own. A third practical limit is that a script is coupled to the specific datasource and processing it was written against, so a script written for a Sentinel-2 true colour composite will not simply work on a Landsat collection or on a Copernicus service, and that coupling is invisible until the response comes back wrong. There is no versioning scheme for individual scripts, and the site publishes the current state rather than a pinned history, so if you depend on someone else's script you should copy it into your own repository and keep it there.

Editorial conclusion

Adopt the custom-scripts approach when you need a visualisation or a derived value that Sentinel Hub processing does not produce out of the box, and write your own script rather than forking the repository when you do not need to publish it. Verify first which datasource and processing combination your script targets, since the same eval script behaves differently across Sentinel-1, Sentinel-2, Landsat and the commercial collections, and check the CC-BY-SA-4.0 terms before reusing a script you did not write in a product of your own.

Frequently asked questions

Official sources

1. Issues
2. License: CC-BY-SA-4.0
3. Project website
4. README
5. sentinel-hub/custom-scripts on GitHub