#Using Tuya CDN Resources

#Version Requirements

• Base library version >=2.26.0
• @ray-js/ray version >=1.6.10
• Developer tools version >=0.10.0
• Cannot be used together with third-party CDN feature

#Feature Description

To reduce the mini program package size, the mini program provides CDN resource functionality. Developers can upload static resources (such as images, audio, etc.) in the project to the CDN, which will be automatically replaced with the corresponding CDN address at runtime.

#Configure CDN

#Project Configuration

Declare the storage directory for the CDN configuration file in project.tuya.json.

{
  "projectname": "miniApp",
  "i18n": true,
  "miniprogramRoot": "app/",  # Mini program source code
+ "publicRoot": "cdn/",    # Storage directory for static resources to be uploaded to CDN
  "projectId": "********",
  "baseversion": "2.10.6",
  "dependencies": {
    "BaseKit": "3.0.3",
    "MiniKit": "3.0.6",
    "BizKit": "3.0.6"
  }
}

Create a new cdn directory in the project root directory with the following structure:

├── package.json
├── project.tuya.json
└── cdn

#Upload to CDN via Developer Tools

After uploading files in the developer tools, a cdnImage.json file will be automatically generated in the cdn directory, for example:

{
  "logo.png": "smart/miniapp/static/bay1754039465669v6sh/17558339266fe39741bbe.jpeg",
  "1.png": "smart/miniapp/static/bay1754039465669v6sh/1755833933000ccbfae02.jpeg"
}

#Usage Limits

• Resources are first pushed to the China region, then synchronized to other regions
• Currently supports storing up to 100MB of static resources

#Feature Description

Upload files:

• IDE upload: Automatically generates Key-Value pairs and writes them to cdnImage.json. To modify the key, manually edit the file
• Platform upload: Manually add the corresponding Key-Value mapping in cdnImage.json

Delete files:

1. First delete the corresponding key-value in cdnImage.json
2. Go to Mini Program Developer Platform to delete the file and free up quota

#Manual Management Examples

#Example 1: Upload Files via IDE

Steps:

1. Click the "Upload CDN File" button in the IDE and select the local image file logo.png
2. The IDE automatically generates the cdnImage.json file with the following content:

{
  "logo.png": "smart/miniapp/static/bay1754039465669v6sh/17558339266fe39741bbe.jpeg"
}

3. Use in code:

import { getCdnUrl } from '@ray-js/ray'
import cdnImage from 'cdn/cdnImage.json'

const logoUrl = getCdnUrl('logo.png', cdnImage)

#Example 2: Upload Files via Developer Platform

Steps:

1. Go to Mini Program Developer Platform to upload image files

2. After successful upload, click the "Copy" button to get the CDN path:

For example, the copied link is:

smart/miniapp/static/bay1754039465669v6sh/1755833933000ccbfae02.jpeg

3. If there is no local cdnImage.json file, initialize it first

   Click the "Initialize cdnImage.json file" button in the IDE:

   

4. Manually add the mapping in the project's cdnImage.json:

{
  "logo.png": "smart/miniapp/static/bay1754039465669v6sh/17558339266fe39741bbe.jpeg",
  "banner.png": "smart/miniapp/static/bay1754039465669v6sh/1755833933000ccbfae02.jpeg"
}

5. Use in code:

import { getCdnUrl } from '@ray-js/ray'
import cdnImage from 'cdn/cdnImage.json'

const bannerUrl = getCdnUrl('banner.png', cdnImage)

#Example 3: Delete or Replace CDN Files

Scenario 1: Completely Delete Files

Assuming you no longer need banner.png:

1. First delete the corresponding record in cdnImage.json:

{
  "logo.png": "smart/miniapp/static/bay1754039465669v6sh/17558339266fe39741bbe.jpeg"
  // Deleted "banner.png" entry
}

2. Go to Mini Program Developer Platform to delete the corresponding CDN file and free up storage quota

3. Ensure that banner.png is no longer referenced in the code to avoid image loading failures

Scenario 2: Replace Files

Assuming you need to update banner.png with a new image:

1. Go to Mini Program Developer Platform to upload the new image

2. Delete the old CDN file (to free up quota)

3. Update the CDN path in cdnImage.json:

{
  "logo.png": "smart/miniapp/static/bay1754039465669v6sh/17558339266fe39741bbe.jpeg",
  "banner.png": "smart/miniapp/static/bay1754039465669v6sh/1755999999000newfile.jpeg"
}

4. The code reference remains unchanged, and the image will automatically use the new CDN address:

import { getCdnUrl } from '@ray-js/ray'
import cdnImage from 'cdn/cdnImage.json'

// key remains unchanged, but loads the new image
const bannerUrl = getCdnUrl('banner.png', cdnImage)

#Using in Projects

#Basic Usage

Ray provides the getCdnUrl method, which automatically replaces images with the corresponding CDN address based on the current region.

Step 1: Import dependencies

import { getCdnUrl } from '@ray-js/ray'
import cdnImage from 'cdn/cdnImage.json'

Step 2: Get CDN address

// Use the complete key path
const logoUrl = getCdnUrl('logo.png', cdnImage)

Step 3: Use in components

import { Image } from '@ray-js/ray'

<Image src={logoUrl} style={{ width: 100, height: 100 }} />

#Complete Example

Assuming the cdnImage.json content is as follows:

{
  "logo.png": "smart/miniapp/static/bay1754039465669v6sh/17558339266fe39741bbe.jpeg",
  "1.png": "smart/miniapp/static/bay1754039465669v6sh/1755833933000ccbfae02.jpeg"
}

Use in React components:

import { getCdnUrl } from '@ray-js/ray'
import React from 'react'
import { Image, View, Text } from '@ray-js/ray'
import cdnImage from 'cdn/cdnImage.json'

const imageStyles = {
  base: {
    display: 'block',
  },
  logo: {
    width: 100,
    height: 100,
    marginBottom: 20,
    borderRadius: 8,
    boxShadow: '0 2px 8px rgba(0,0,0,0.1)',
  },
  banner: {
    width: 200,
    height: 200,
    borderRadius: 12,
    boxShadow: '0 4px 12px rgba(0,0,0,0.15)',
    border: '1px solid #eee',
  },
}

export default function Home() {
  // Pre-process CDN URLs to avoid repeated calls
  const logoUrl = getCdnUrl('logo.png', cdnImage)
  const bannerUrl = getCdnUrl('1.png', cdnImage)

  return (
    <View>
      <Text>Hello CDN</Text>
      <Image src={logoUrl} style={{ ...imageStyles.base, ...imageStyles.logo }} />
      <Image src={bannerUrl} style={{ ...imageStyles.base, ...imageStyles.banner }} />
    </View>
  )
}

#Notes

• It is recommended to pre-process URLs outside the component or in useMemo to avoid calling on every render
• CDN addresses will automatically select the nearest node based on the user's region, improving loading speed

#FAQ

Q1: Is the 100MB quota per project or shared across all projects?

A: The 100MB is the total quota for all mini program projects within the current workspace, not per project.

• Multiple mini program projects within the same workspace share this 100MB of storage space
• If there is workspace authorization, the quota of the parent account (workspace owner) applies
• For example: If A authorizes B, when B operates in A's workspace, A's CDN quota is used

Q2: How to free up CDN quota?

A: You must go to the Mini Program Developer Platform to delete files to free up quota. Simply deleting the cdn/cdnImage.json file or its entries in your project will NOT free up CDN quota.

Correct deletion process:

1. First delete the corresponding key-value in the project's cdnImage.json (to avoid broken references in code)
2. Go to the developer platform to delete the corresponding CDN file (to free up quota)

Q3: What if I run out of quota?

A:

1. Go to the developer platform to view uploaded files and delete unused resources to free up quota
2. Optimize image sizes before uploading, use compression tools (such as TinyPNG) to reduce file size

Q4: What if I accidentally deleted the cdnImage.json file?

A: cdnImage.json is only a local mapping file. After deletion:

1. CDN files on the developer platform still exist, and quota is not freed
2. You can click the "Initialize cdnImage.json file" button in the IDE to generate an empty template
3. Go to the developer platform to view uploaded files and manually rebuild the mapping