## 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`.

```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:

```json
{
  "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

| Operation | IDE | Developer Platform |
|------|-----|-----------|
| Initialize configuration file | ✓ | - |
| Upload files | ✓ | ✓ |
| View files | - | ✓ |
| Delete files | - | ✓ |

**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](https://platform.tuya.com/miniapp) 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:

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

3. Use in code:

```tsx
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](https://platform.tuya.com/miniapp) to upload image files

<Image src='/images/guide/cdn/upload_en.png'/>
<Image src='/images/guide/cdn/upload-button_en.png'/>

2. After successful upload, click the "Copy" button to get the CDN path:
<Image src='/images/guide/cdn/copy_link_en.png'/>
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:

   <Image src='/images/guide/cdn/init_cdn_en.png'/>

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

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

5. Use in code:

```tsx
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`:

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

2. Go to [Mini Program Developer Platform](https://platform.tuya.com/miniapp) 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](https://platform.tuya.com/miniapp) to upload the new image

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

3. Update the CDN path in `cdnImage.json`:

```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:

```tsx
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**

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

**Step 2: Get CDN address**

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

**Step 3: Use in components**

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

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

#### Complete Example

Assuming the `cdnImage.json` content is as follows:

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

Use in React components:

```tsx
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](https://platform.tuya.com/miniapp) 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