Amos Framework

1.13.2 verified Tue Apr 21 auth: no javascript

Amos Framework is a UI component library for JavaScript and TypeScript applications, providing a comprehensive collection of pre-built components, utilities, and tools. Currently at version 1.13.2, it offers a wide array of UI elements such as Button, Input, Form, Layout, and various utility functions like `message` and `Toast`. A key differentiator is its application-specific licensing mechanism, which mandates either a `license.dat` file or global configuration via `window.__amos__license__`. It supports modular, on-demand loading of components through a custom Babel plugin for optimized bundling. The framework emphasizes specific integration patterns for webpack (e.g., configuring externals) and custom Babel setups, making it less of a plug-and-play solution than some alternatives due to its explicit license management and toolkit-driven modularity. Its release cadence is not explicitly stated but appears stable, with updates reflected in its versioning.

Common errors

error License verification failed: No license found or invalid format ↓

cause The framework's internal license check failed because `license.dat` is missing, or `window.__amos__license__` is not set or contains an invalid value.

fix

Ensure license.dat is in your project root, or set window.__amos__license__ to a valid license string or object as specified in the README. Use window.__amos__license__ = 'test'; for quick development.

error TypeError: Cannot read properties of undefined (reading 'info') ↓

cause A utility method (like `message.info`) or component is being accessed before it is correctly imported or before the framework is fully initialized, potentially due to a license issue or incorrect import path.

fix

Verify that import { message } from 'amos-framework'; is present and that the framework's license is successfully loaded and validated. Check console for license-related errors.

error Warning: React.createElement: type is invalid -- expected a string (for built-in components) or a class/function (for composite components)... ↓

cause An Amos Framework component is not being recognized as a valid React component. This can be caused by incorrect import paths, CommonJS/ESM module mismatches, or an improper webpack `externals` configuration.

fix

Double-check your component imports (e.g., import { Button } from 'amos-framework';). If using webpack, ensure externals are configured as specified in the '添加 sdk license' section.

error ReferenceError: amosframework is not defined ↓

cause An attempt was made to access `amosframework` globally (e.g., in an embedded script tag or through a bundler that expects global access) without the UMD build being correctly loaded into the HTML or the webpack `externals` being configured to expose it.

fix

If using UMD, ensure <script src="/extra/amosframework/amosframework.min.js"></script> is loaded *before* your application scripts. If using a bundler, configure webpack externals as described in the documentation.

Warnings

gotcha Amos Framework requires a license for full functionality, which must be provided either via a `license.dat` file in the project root or by setting `window.__amos__license__` globally in your application. ↓

fix Follow the '添加 sdk license' section in the README: copy `lib/licenseSdk.js` and run `npm run dist`, or programmatically set `window.__amos__license__` with a valid license key or object (e.g., `window.__amos__license__ = 'test'` for development).

gotcha When using the `findAllByType` method with custom or compiled components, explicitly set `__AMOS_TYPE__` or `displayName` on your component class/function to ensure correct type matching, as minified `name` properties can cause exceptions. ↓

fix For a component like `const MyButton = (props) => <Button {...props}/>;`, add `MyButton.__AMOS_TYPE__ = 'Button';` to guarantee proper identification by `findAllByType`.

gotcha Integrating Amos Framework into a webpack project requires specific configuration of `externals` for `react`, `react-dom`, and `amos-framework` itself. Failing to do so can lead to bundling issues, duplicate React instances, or incorrect global access for UMD builds. ↓

fix Add the following to your webpack configuration: `webpackConfig.externals = { 'react': 'React', 'react-dom': 'ReactDOM', 'amos-framework': 'amosframework' };`

gotcha On-demand loading and tree-shaking for Amos Framework components depend on a custom Babel plugin (`AFImportPlugin.js`) built using `ray-pack-toolkit/lib/babel/SplitImportPlugin` and `amos-framework/lib/moduleMapping`. Without this specific Babel configuration, the entire framework bundle will be imported, negating optimization benefits. ↓

fix Refer to the '按需加载模块' section of the README to create and configure the necessary Babel plugin, ensuring `ray-pack-toolkit` is installed as a development dependency.

Install

npm install amos-framework

yarn add amos-framework

pnpm add amos-framework

Imports

Button
wrong
```
const Button = require('amos-framework').Button;
```
correct
```
import { Button } from 'amos-framework';
```
Components are typically imported as named exports from the main package. CommonJS `require` might lead to issues if the build target is primarily ESM.
message
wrong
```
import message from 'amos-framework/lib/message';
```
correct
```
import { message } from 'amos-framework';
```
Utility functions like `message` are also named exports. Direct subpath imports may bypass intended bundling or cause issues.
findAllByType
wrong
```
window.amosframework.findAllByType;
```
correct
```
import { findAllByType } from 'amos-framework';
```
Although the framework can be exposed globally as 'amosframework' in UMD builds, modern applications should use ES module imports. Global access is intended for specific embedding scenarios.
moduleMapping
wrong
```
import { moduleMapping } from 'amos-framework';
```
correct
```
import moduleMapping from 'amos-framework/lib/moduleMapping';
```
This specific utility is a default export from a subpath and is primarily used for configuring the Babel split import plugin, not for direct application logic.

Quickstart

Demonstrates importing and using core Amos Framework UI components (Button, Input, Form) and the message utility, including basic state management and the required development license initialization.

import React from 'react';
import ReactDOM from 'react-dom/client';
import { Button, Input, message, Form, Layout, Row, Col } from 'amos-framework';
// Ensure framework styles are loaded. Example (actual path may vary based on build):
// import 'amos-framework/dist/amosframework.min.css';

// IMPORTANT: Simulate license setup for development. 
// For production, follow the official licensing guide.
// This can be a string key or an object based on your license type.
window.__amos__license__ = 'test'; // Quick start development license

const App = () => {
  const [inputValue, setInputValue] = React.useState('');

  const handleClick = () => {
    message.info('Button clicked! Input: ' + inputValue);
  };

  const handleSubmit = (e) => {
    e.preventDefault();
    message.success(`Form submitted with value: ${inputValue}`);
  };

  return (
    <Layout style={{ minHeight: '100vh', padding: '20px' }}>
      <Row justify="center" align="middle">
        <Col span={12} style={{ maxWidth: '600px', width: '100%' }}>
          <h1>Amos Framework Basic Usage</h1>
          <Form onSubmit={handleSubmit} style={{ marginBottom: '20px' }}>
            <Input
              value={inputValue}
              onChange={(e) => setInputValue(e.target.value)}
              placeholder="Enter some text..."
              style={{ width: '100%', marginBottom: '10px' }}
            />
            <Button type="primary" onClick={handleClick}>
              Show Message
            </Button>
            <Button type="submit" style={{ marginLeft: '10px' }}>
              Submit Form
            </Button>
          </Form>
          <p>
            This simple application demonstrates how to import and utilize core Amos Framework UI components like `Button`, `Input`, `Form`, `Layout`, and the `message` utility. It also highlights the crucial step of initializing the framework's license for local development, which is a mandatory requirement. For a full setup, ensure React and ReactDOM are available, and the framework's CSS is properly loaded into your project.
          </p>
        </Col>
      </Row>
    </Layout>
  );
};

const rootElement = document.getElementById('root');
if (rootElement) {
  const root = ReactDOM.createRoot(rootElement);
  root.render(<App />);
} else {
  console.error("Root element 'root' not found. Please add <div id='root'></div> to your HTML.");
}