Object Storage Service:Install OSS SDK for Browser.js

Prerequisites

Before you begin, ensure that you have:

• A RAM user or Security Token Service (STS) temporary credentials configured for OSS access

• CORS rules configured on your bucket (required for all browser-based requests)

Configure browser access

Browsers enforce two security boundaries that require upfront configuration before your app can reach OSS:

• Cross-origin resource sharing (CORS): Browsers block requests to a different origin by default. Configure CORS rules on your bucket to allow your web app's domain.

• Temporary credentials: Never embed a long-term AccessKey pair in client-side code — it exposes your credentials to anyone who views the page source. Use STS to issue short-lived tokens instead.

Configure CORS rules

In the OSS console, add a CORS rule to your bucket with the following settings:

Field	Value	Notes
Source	https://your-domain.com or https://*.your-domain.com	Use a wildcard (*) only for development
Allowed methods	Select based on your requirements	For example, select PUT for multipart upload and DELETE to delete objects
Allowed headers	*	Required for SDK request headers
Exposed headers	ETag, x-oss-request-id, x-oss-version-id	Select based on your requirements

For detailed steps, see Configure CORS.

Important

The wildcard origin (*) is convenient for development but grants access to any domain. In production, specify exact origins to limit access to your application.

Install the SDK

OSS SDK for Browser.js uses Browserify and Babel to compile code for browser environments.

npm install ali-oss

const OSS = require('ali-oss');

<!-- Load from Alibaba Cloud CDN -->
<script src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.20.0.min.js"></script>

<!-- Or load from a local copy -->
<script src="./aliyun-oss-sdk-6.20.0.min.js"></script>

Initialize the client

Both installation methods use new OSS() to create a client. Pass your STS credentials and a refreshSTSToken function that fetches fresh credentials before they expire.

const client = new OSS({
  // Region where the bucket is located, e.g., oss-cn-hangzhou
  region: '<region-id>',
  // Use V4 request signing
  authorizationV4: true,
  // Temporary credentials from STS
  accessKeyId: '<sts-access-key-id>',
  accessKeySecret: '<sts-access-key-secret>',
  stsToken: '<sts-token>',
  // Fetch fresh credentials before expiry
  refreshSTSToken: async () => {
    const response = await fetch('<your-sts-endpoint>');
    const info = await response.json();
    return {
      accessKeyId: info.accessKeyId,
      accessKeySecret: info.accessKeySecret,
      stsToken: info.stsToken,
    };
  },
  // Refresh interval in milliseconds (5 minutes)
  refreshSTSTokenInterval: 300000,
  // Target bucket
  bucket: '<bucket-name>',
});

Replace the following placeholders:

Use the SDK

All API operations return a Promise. The SDK supports both async/await and Promise chaining.

async function uploadFile(file) {
  try {
    // object: the key under which the file is stored in OSS
    // file: a File or Blob object from the browser
    const result = await client.put('uploads/my-file.jpg', file);
    console.log('Upload successful:', result.url);
  } catch (err) {
    console.error('Upload failed:', err);
  }
}

client
  .put('uploads/my-file.jpg', file)
  .then((result) => {
    console.log('Upload successful:', result.url);
    return client.get('uploads/my-file.jpg');
  })
  .then((downloaded) => {
    console.log('Download successful:', downloaded);
  })
  .catch((err) => {
    console.error('Error:', err);
  });

Supported browsers

Limitations

The following features are not available in browser environments:

SDK resources

• GitHub repository — source code and issues

• API reference — all supported operations

• Changelog — version history

This documentation covers SDK v6.x. For v5.x, see the v5.x README. To upgrade from v5.x to v6.x, follow the upgrade guide.

What's next

• Permissions and access control — RAM policies and access control for OSS

• Use temporary credentials provided by STS to access OSS — end-to-end STS integration guide

• Configure CORS — detailed CORS configuration steps