Upload JS API Library

A TypeScript 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. You can use it in any JavaScript or TypeScript project.

Features

• Multipart file upload support.
• Progress tracking with detailed statistics.
• Error handling and status reporting.
• React integration.
• TypeScript type safety.
• Customizable upload endpoints.
• Support for different output types.
• Cancel upload functionality.

Progress Tracking

The library provides detailed progress information including:

• Uploaded bytes
• Total file size
• Elapsed time
• Bitrate
• Estimated remaining time

Instalation

NPM

npm install @maptiler/upload-js

Yarn

yarn add @maptiler/upload-js

Using UploadAPI

The 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.

Server-side

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.

Checkout the packages/example/app/api to learn how easily these features can be integrated into your ecosystem.

Client-side

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, message) => 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`,
})

// You can now start the upload:
api.start()

// or cancel the upload:
api.cancel()

Reference

This reference documents every object, classes, types and method available in the MapTiler Upload JS.

Example

Try the Next.js example to see how easily you can use this library.