A TypeScript & Javascript library for handling large file uploads with multipart support and progress tracking. The Upload JS provides a simple way to upload files to MapTiler, track progress, and handle errors.
📖 Documentation 📦 NPM Package 🌐 Website 🔑 Get API Key
Table of Contents
npm install @maptiler/upload-jsyarn add @maptiler/upload-jsThe UploadAPI class provides a simple way to upload files to MapTiler, track progress, and handle errors.
You can use it in any JavaScript or TypeScript project.
You have to implement the API endpoints in your backend to proxy requests to MapTiler.
The library expose helper functions designed to simplify server-side integration with MapTiler. They provide ready-to-use route handlers for initializing, processing, replacing, and canceling uploads, so you don’t have to write the fetch logic yourself.
import {
initUpload,
processUpload,
replaceUpload,
cancelUpload,
} from "@maptiler/upload-js";All functions require serviceToken – the MapTiler service token is a private key used to authenticate your
application with MapTiler services. This token grants access to your MapTiler account and allows your server to
perform actions such as uploading files, managing datasets, and more.
Caution
🚨 The service token must never be exposed to the client/browser. It should only be used on the server.
Tip
See packages/example/app/api how easily the functions can be integrated into your ecosystem.
import { HttpStatusCode } from "axios";
import { ApiConfig, OutputType, UploadAPI } from "@maptiler/upload-js";
// The UploadAPI class is a wrapper around the upload process.
const api = await UploadAPI.initialize({
file, // File
outputType, // OutputType | null
onChange: (api: UploadAPI) => {
// Update your UI with progress or status.
// api.getProgress()
// api.getStatus())
},
onError: (error: HttpStatusCode, message: string, api: UploadAPI | null) => {
alert(`${error}, ${message}`);
},
// These API endpoints must point to your backend, which can use the provided server-side helpers to
// proxy requests to MapTiler.
initializeURI: datasetID ? `/api/${datasetID}/ingest` : "/api/ingest",
getProcessURI: (id) => `/api/ingest/${id}/process`,
getCancelURI: (id) => `/api/ingest/${id}/cancel`,
// Auto upload, default = true. Upload will start immediately.
autoUpload: false,
});
// You can now start the upload:
api.start();
// or cancel the upload:
api.cancel();This repository contains a Next.js example showing how easily you can use this library.
Create a .env file in the packages/example directory and add your MapTiler service token:
MAPTILER_SERVICE_TOKEN=<your-own-service-token>
You can find your service token in your MapTiler account.
You can run the entire application inside a development container without installing any dependencies locally.
- Install Node.js (v18.18 or later).
- Install Yarn – see the official guide.
- Install dependencies:
yarn installStart the example application in development mode:
yarn example [-p PORT]Open your browser at http://localhost:3000 (or your chosen port).
For detailed guides, API reference, and advanced examples, visit our comprehensive documentation:
- 📚 Documentation - Comprehensive guides and API reference
- ✉️ Contact us - Get in touch or submit a request
- 🐦 Twitter/X - Follow us for updates
We love contributions from the community! Whether it's bug reports, feature requests, or pull requests, all contributions are welcome:
- Fork the repository and create your branch from
main - If you've added code, add tests that cover your changes
- Ensure your code follows our style guidelines
- Give your pull request a clear, descriptive summary
- Open a Pull Request with a comprehensive description
This project is licensed under the BSD 3-Clause License – see the LICENSE file for details.
💜 Made with love by the MapTiler team