{"id":15510,"library":"amos-framework","title":"Amos Framework","description":"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.","status":"active","version":"1.13.2","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install amos-framework","lang":"bash","label":"npm"},{"cmd":"yarn add amos-framework","lang":"bash","label":"yarn"},{"cmd":"pnpm add amos-framework","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core peer dependency for UI components, required for rendering. Expected as an external in build configurations.","package":"react","optional":false},{"reason":"Core peer dependency for rendering UI components. Expected as an external in build configurations.","package":"react-dom","optional":false},{"reason":"Required for the framework's licensing mechanism, specifically for `lib/licenseSdk.js`.","package":"amos-authorization","optional":true},{"reason":"Provides `SplitImportPlugin` for implementing custom Babel plugins for on-demand component loading.","package":"ray-pack-toolkit","optional":true}],"imports":[{"note":"Components are typically imported as named exports from the main package. CommonJS `require` might lead to issues if the build target is primarily ESM.","wrong":"const Button = require('amos-framework').Button;","symbol":"Button","correct":"import { Button } from 'amos-framework';"},{"note":"Utility functions like `message` are also named exports. Direct subpath imports may bypass intended bundling or cause issues.","wrong":"import message from 'amos-framework/lib/message';","symbol":"message","correct":"import { message } from 'amos-framework';"},{"note":"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.","wrong":"window.amosframework.findAllByType;","symbol":"findAllByType","correct":"import { findAllByType } from 'amos-framework';"},{"note":"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.","wrong":"import { moduleMapping } from 'amos-framework';","symbol":"moduleMapping","correct":"import moduleMapping from 'amos-framework/lib/moduleMapping';"}],"quickstart":{"code":"import React from 'react';\nimport ReactDOM from 'react-dom/client';\nimport { Button, Input, message, Form, Layout, Row, Col } from 'amos-framework';\n// Ensure framework styles are loaded. Example (actual path may vary based on build):\n// import 'amos-framework/dist/amosframework.min.css';\n\n// IMPORTANT: Simulate license setup for development. \n// For production, follow the official licensing guide.\n// This can be a string key or an object based on your license type.\nwindow.__amos__license__ = 'test'; // Quick start development license\n\nconst App = () => {\n  const [inputValue, setInputValue] = React.useState('');\n\n  const handleClick = () => {\n    message.info('Button clicked! Input: ' + inputValue);\n  };\n\n  const handleSubmit = (e) => {\n    e.preventDefault();\n    message.success(`Form submitted with value: ${inputValue}`);\n  };\n\n  return (\n    <Layout style={{ minHeight: '100vh', padding: '20px' }}>\n      <Row justify=\"center\" align=\"middle\">\n        <Col span={12} style={{ maxWidth: '600px', width: '100%' }}>\n          <h1>Amos Framework Basic Usage</h1>\n          <Form onSubmit={handleSubmit} style={{ marginBottom: '20px' }}>\n            <Input\n              value={inputValue}\n              onChange={(e) => setInputValue(e.target.value)}\n              placeholder=\"Enter some text...\"\n              style={{ width: '100%', marginBottom: '10px' }}\n            />\n            <Button type=\"primary\" onClick={handleClick}>\n              Show Message\n            </Button>\n            <Button type=\"submit\" style={{ marginLeft: '10px' }}>\n              Submit Form\n            </Button>\n          </Form>\n          <p>\n            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.\n          </p>\n        </Col>\n      </Row>\n    </Layout>\n  );\n};\n\nconst rootElement = document.getElementById('root');\nif (rootElement) {\n  const root = ReactDOM.createRoot(rootElement);\n  root.render(<App />);\n} else {\n  console.error(\"Root element 'root' not found. Please add <div id='root'></div> to your HTML.\");\n}\n","lang":"javascript","description":"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."},"warnings":[{"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).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For a component like `const MyButton = (props) => <Button {...props}/>;`, add `MyButton.__AMOS_TYPE__ = 'Button';` to guarantee proper identification by `findAllByType`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add the following to your webpack configuration: `webpackConfig.externals = { 'react': 'React', 'react-dom': 'ReactDOM', 'amos-framework': 'amosframework' };`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"License verification failed: No license found or invalid format"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'info')"},{"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.","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.","error":"Warning: React.createElement: type is invalid -- expected a string (for built-in components) or a class/function (for composite components)..."},{"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.","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.","error":"ReferenceError: amosframework is not defined"}],"ecosystem":"npm"}