#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

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.

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

#Image Compression

If local images must be used:

• Use appropriate formats
• Avoid base64 inlining of large assets
• Compress images with tools like Tinypng
• Control image dimensions; avoid loading images larger than needed for display

#Dependency Selection and Import

Pay attention to package size when choosing dependencies:

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

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

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

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

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:

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

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

#Checklist