Amos Framework

Common errors

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

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

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

• 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 npm
• yarn add amos-framework yarn
• pnpm add amos-framework pnpm

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.");
}