---
title: Package Size Optimization
docType: default
---

# Package Size Optimization

Package size directly affects miniapp download time. The larger the package, the longer the download time on first open and version updates. Controlling package size is one of the most effective strategies for startup performance optimization.

## Use Subpackage Loading

Subpackage loading is the most effective way to control startup package size. By splitting the miniapp into multiple subpackages, only the main package needs to be downloaded at startup; other subpackages are loaded on demand. [Subpackage Loading](/en/miniapp/develop/miniapp/guide/ability/sub-packages)

**Recommended for**: Projects with a package size exceeding 2MB

### Optimization Tips

- Place **pages not needed at startup** into subpackages
- Keep only necessary shared resources and startup pages in the main package
- Plan subpackage structure carefully to avoid any single subpackage becoming too large

## Remove Unused Code and Assets

As projects iterate, packages may accumulate large amounts of unused code and resource files.

### How to Identify

1. **Check unreferenced pages**: Pages registered in `app.json` but not actually used
2. **Check unreferenced components**: Custom components declared in JSON but not used
3. **Check unreferenced assets**: Images, fonts, and other files in the project that are not referenced
4. **Check unused dependencies**: npm packages installed in `package.json` but not used

### Bundle Analysis

`@ray-js/cli` provides built-in bundle analysis. It generates a structured metafile during build that, combined with a visualization tool, quickly identifies dependencies with abnormal size. [Ray Bundle Analysis](/en/miniapp/develop/ray/guide/optimization/startup/bundle-analysis).

## Image and Asset Optimization

Images and assets are typically the biggest contributors to package size.

### Upload Images to CDN

Upload static assets (images, audio, etc.) to CDN. At runtime they are automatically replaced with CDN URLs, reducing package size. [Tuya CDN Guide](/en/miniapp/develop/ray/guide/cdn/tuya_cdn).

### Image Compression

If local images must be used:

- Use appropriate formats
- Avoid base64 inlining of large assets
- Compress images with tools like [Tinypng](https://tinypng.com/)
- Control image dimensions; avoid loading images larger than needed for display

## Dependency Selection and Import

Pay attention to package size when choosing dependencies:

```javascript
// Recommended: lightweight utility library
import dayjs from 'dayjs'; // ~2KB

// Avoid: heavyweight library
import moment from 'moment'; // ~70KB
```

For libraries that support tree-shaking, avoid importing everything:

```javascript
// Recommended: import on demand
import debounce from 'lodash/debounce';

// Avoid: full import
import { debounce } from 'lodash';
```

## Remove react-dom

**Requirement**: @ray-js/ray >= 1.7.39

Newer versions of Ray have removed the mistakenly included `react-dom` dependency. After upgrading, the business bundle can be reduced by 100KB+. Simply upgrade the Ray version to take effect.

<Image src="/images/guide/optimization/react-dom-bundle.png" width="600px" />

## Remove Redundant iconfont

**Requirement**: @ray-js/ray >= 1.6.0

In older versions, any page importing `@ray-js/ray` would bundle the full `iconfont.css`, causing every page to carry a redundant copy of the icon font styles. After upgrading to @ray-js/ray >= 1.6.0, `iconfont.css` is imported on demand — only when icons are actually used — which noticeably reduces package size.

```js
// After `@ray-js/ray@1.6.0`, Icon is no longer built in; install `@ray-js/icons` separately
import { Icon } from '@ray-js/icons';
```

## Smart-UI On-Demand Loading

**Applicable to**: Projects using Smart-UI

**Requirements**:
- `@ray-js/cli` >= 1.7.4
- esbuild build mode (webpack not supported)
- ESModule `import` syntax
- SmartUI >= 2.4.0

After configuration, the build automatically converts full Smart-UI imports to on-demand imports. Add `importTransformer` in `ray.config.ts`:

```typescript
import { RayConfig } from '@ray-js/types';
import SmartUIAutoImport from '@ray-js/smart-ui/lib/auto-import';

const config: RayConfig = {
  // ...
  importTransformer: [SmartUIAutoImport],
};

export default config;
```

Effect after configuration:

```typescript
// Before build
import { Button } from '@ray-js/smart-ui';

// After build (auto-transformed)
import { Button } from '@ray-js/smart-ui/es/button';
```

## Checklist

| Check Item | Optimization |
| ---------- | ------------ |
| Package size exceeds 2MB | Use subpackage loading; only download main package at startup |
| Unused dependencies, components, or assets | Use bundle analysis to identify and remove |
| Large third-party libraries | Replace with lightweight alternatives or use on-demand imports |
| Local image assets | Upload to CDN or compress before referencing |
| Full Smart-UI import | Configure `importTransformer` for on-demand loading |
| Outdated Ray version | Upgrade to >= 1.6.0 to remove redundant iconfont; >= 1.7.39 to remove react-dom |