{"slug": "announcing-nocobase-2-2", "title": "Announcing NocoBase 2.2", "summary": "NocoBase 2.2 introduces a new independent `/v/` frontend entry that removes legacy V1 compatibility, offering significant performance improvements and becoming the primary target for future development. The release also upgrades file access with stable URLs and permission checks, and improves the comment block, AI knowledge base, workflows, and V2 compatibility across core plugins. Users can control the default entry mode via the `APP_CLIENT_ENTRY_MODE` environment variable, with options including `legacy-default`, `modern-default`, and `modern-only`.", "body_md": "**NocoBase 2.2 further completes the end-to-end V2 experience.** With the independent `/v/`\n\nfrontend entry and the new mobile experience now available, V2 is no longer just a redesigned page experience—it is becoming a more independent and lightweight frontend runtime. This release also upgrades the file access mechanism and continues to improve the comment block, AI knowledge base, workflows, and V2 compatibility across core plugins.\n\nIf your application already relies primarily on V2 pages, 2.2 provides a more complete and lightweight V2 experience. If your application still mainly uses V1 pages, we recommend migrating your pages and plugins before switching to the new `/v/`\n\nentry.\n\n## New features\n\n### New independent `/v/`\n\nfrontend entry\n\n`/v/`\n\nis a new, independently built frontend entry. NocoBase 2.0 introduced a major frontend refactor while retaining compatibility with V1 modules and pages. The `/v/`\n\nbuild removes this legacy V1 compatibility: it can no longer create or render V1 pages and blocks and includes only V2 capabilities. It also delivers significant performance improvements and will become the primary target for future NocoBase development.\n\nIf your production application already consists entirely of V2 pages, you can consider adopting the\n\n`/v/`\n\nentry.If your application mainly uses V2 pages but still contains a small number of V1 pages, migrate those pages to V2 first.\n\nIf your application still mainly uses V1 pages, we do not recommend switching directly to\n\n`/v/`\n\n. Migrate the pages and related plugins first.\n\nIn most cases, you can enter the new frontend by adding the `/v/`\n\nprefix to an existing path:\n\n```\n# Original path\nhttps://nocobase.example.com/admin/1xl0epqn6q3\n\n# Independent V2 entry\nhttps://nocobase.example.com/v/admin/1xl0epqn6q3\n```\n\n#### Set the default application entry\n\nUse the `APP_CLIENT_ENTRY_MODE`\n\nenvironment variable to control the application entry mode:\n\n`legacy-default`\n\n: both`/`\n\nand`/v/`\n\nare available;`/`\n\nis the default entry`modern-default`\n\n: both`/`\n\nand`/v/`\n\nare available;`/v/`\n\nis the default entry`modern-only`\n\n: only`/v/`\n\nis available\n\n#### Current status of `/v/`\n\nThe `/v/`\n\nentry is being introduced progressively. It has several notable differences:\n\n- Pages created with Page V1 are no longer displayed under\n`/v/`\n\n. Pages created with Page V2 continue to work normally. - Plugins adapted only for\n`client-v1`\n\nare not loaded under`/v/`\n\n. The`/v/`\n\nentry loads only plugins adapted for`client-v2`\n\n. See the[client plugin development documentation](https://docs.nocobase.com/plugin-development/client/)for details.\n\nMost built-in NocoBase plugins have been adapted and migrated to client-v2 in this release, so most features are ready to use. A small number of plugins have not yet been migrated and will be handled progressively. Some plugin capabilities will receive future updates only under `/v/`\n\n. Current differences include:\n\n- The plugin list no longer shows deprecated plugins or plugins that support only NocoBase 1.x\n- New Page V1 pages can no longer be created\n- Public forms distinguish between V1 and V2, and V1 public forms are not displayed under\n`/v/`\n\n- Approval workflows require their related UI to be reconfigured before they can be used under\n`/v/`\n\n- The new mobile experience is available only under\n`/v/`\n\n- The “AI employees / Data sources” tab has been removed\n- Comment, calendar, expression, and external data collections have been removed\n- Workflow manual nodes are not yet supported under\n`/v/`\n\n- Badge counts cannot yet be added to menus\n\nPlan the migration to `/v/`\n\naccording to your production environment and current use of V1 and V2 features.\n\nRelated documentation:\n\n### File access upgrade: stable URLs, permission checks, and deployment changes\n\nNocoBase 2.2 introduces an important upgrade to the access mechanism for NocoBase-managed files. By default, attachments and files no longer expose local storage paths, object storage URLs, or presigned URLs as their business URLs. Instead, they use stable NocoBase URLs:\n\n```\n/files/<app>/<dataSource>/<collection>/<id><extname>\n```\n\nFor example:\n\n```\n/files/main/main/attachments/42.pdf\n```\n\nIf `APP_PUBLIC_PATH=/nocobase`\n\nis configured, the corresponding subpath is added automatically:\n\n```\n/nocobase/files/main/main/attachments/42.pdf\n```\n\nWhen a stable URL is accessed, the request first goes to NocoBase. NocoBase checks the current user, role, view permission, and data scope for the target attachment or file collection. Once the check succeeds, NocoBase responds with a `302`\n\nredirect to the actual URL generated by the storage engine.\n\n```\nStable URL → NocoBase identity and permission checks → 302 → Local or object storage URL\n```\n\nThis separates business content from physical storage addresses. If you change a bucket, CDN domain, signing strategy, or thumbnail rule, stable URLs already stored in business fields usually do not need to be updated. The everyday workflows for uploading attachments, displaying images, previewing files, and downloading files remain essentially unchanged.\n\n#### Configure file URLs and public access independently\n\nFor file storage engines, **NocoBase URL** is the recommended default so that file access follows NocoBase role and data permissions. NocoBase 2.2 also provides separate options for scenarios that require direct storage URLs or public access:\n\n**Original URL**: returns the storage engine URL directly, without NocoBase permission checks** Allow public access**: continues to return a NocoBase URL but skips file-record permission checks when the URL is accessed\n\nBoth Original URL and Allow public access expand the scope from which files can be accessed, so configure them carefully for your use case. After the settings are saved, the API response behavior changes for both existing and new files under the same storage engine, but no files are moved or uploaded again.\n\n#### Check deployment configuration before upgrading\n\n`/files/`\n\nis an authenticated NocoBase application route. It must not be handled as a static directory or fall through to the frontend SPA’s `index.html`\n\nfallback. Nginx and Caddy configurations generated by the current NocoBase CLI include the required rules automatically. If you maintain your reverse proxy manually, verify that:\n\n`/files/`\n\nis forwarded to NocoBase and evaluated before the SPA fallback rule- When\n`APP_PUBLIC_PATH`\n\nis configured, the corresponding subpath`/files/`\n\nroute is also forwarded, while the root`/files/`\n\nroute remains available for compatibility - The\n`302 Location`\n\nreturned by a stable URL is not cached - When a page accesses the API cross-origin, its origin is included in\n`CORS_ORIGIN_WHITELIST`\n\n- All cluster nodes and replicas are upgraded together so that\n`/files/`\n\nrequests cannot reach an older node - When using an external NocoBase data source, the consuming instance and its related plugins are upgraded before the source instance\n\nNote:Existing`/storage/uploads/...`\n\n, CDN, and object storage URLs stored in historical Markdown, rich text, or business fields are not rewritten automatically. Once the new version is running, newly uploaded files and newly edited content may contain`/files/...`\n\nURLs, which older versions do not recognize. Environments with strict rollback requirements should retain a database snapshot before reopening write access and verify the reverse proxy configuration in advance.\n\n#### Security boundaries\n\nStable URLs provide a permission check before access, but NocoBase does not continuously proxy the file content. After permission checks succeed, the browser can still see the final storage URL. If that URL points to a public bucket, a public CDN, or an openly accessible local static directory, anyone who obtains it may still bypass NocoBase.\n\nFor sensitive files such as contracts, identity documents, and internal materials, use storage-side controls such as private storage, short-lived signed URLs, or CDN authentication. For online Office previews, NocoBase issues a short-lived URL bound to the current file after the user’s permissions are validated. This URL is valid for 10 minutes by default and must not be stored or distributed as a long-term sharing link.\n\nRelated documentation:\n\n[File manager: Stable URLs](https://docs.nocobase.com/file-manager/stable-url)[File storage engines and access control](https://docs.nocobase.com/file-manager/storage/)[Environment variables](https://docs.nocobase.com/get-started/installation/env)[Production deployment](https://docs.nocobase.com/get-started/deployment/production)[Nginx reverse proxy](https://docs.nocobase.com/nocobase-cli/production/reverse-proxy/nginx)[Caddy reverse proxy](https://docs.nocobase.com/nocobase-cli/production/reverse-proxy/caddy)\n\n### New mobile experience (`/v/`\n\nonly)\n\nThe new mobile experience provides a `/v/mobile`\n\nentry with a dedicated mobile layout.\n\nMobile and desktop layouts share the same data sources and business data, while their menus, routes, and page content can be configured independently. This makes it possible to reorganize pages around mobile usage patterns and use a bottom tab bar as the primary navigation, which is better suited to mobile devices.\n\nNocoBase 2.2 further improves interactions such as mobile tab bars, scrolling in half-screen panels, embedded pages, and permission controls, making data entry, queries, approvals, and task processing more reliable.\n\nRelated documentation:\n\n### New comment block\n\nThe new comment block is no longer limited to the comments collection in the main data source and no longer needs to be used as a relationship block. You can add it to a record detail page or popup for tasks, articles, tickets, customers, and other records, allowing users to view, reply to, and add comments in the context of the current record.\n\nRelated documentation:\n\n### AI knowledge base enhancements\n\nThe AI knowledge base has been migrated to client-v2 and now offers improved knowledge base and vector storage configuration:\n\n- When a workflow creates a knowledge base document, it can overwrite an existing document with the same document key\n- Vector databases can be configured and managed\n- Configuration entries are available for external knowledge bases and external vector storage extensions, allowing developers to use plugins to integrate vector databases or third-party retrieval services that NocoBase does not yet support out of the box\n\nRelated documentation:\n\n### Workflow: Database transaction node\n\nThe new database transaction node runs a group of database operations within the same transaction. It is designed for scenarios in which multiple data-processing steps must either all succeed or all roll back—for example, creating an order, reducing inventory, writing order line items, and updating the order status.\n\nRelated documentation:\n\n## V2 compatibility and experience improvements\n\nIn addition to the new features above, NocoBase 2.2 continues to migrate and improve the V2 interfaces and interactions of commonly used features:\n\n- User, department, and permission settings\n- User data synchronization\n- DingTalk authentication, synchronization, and notification settings\n- WeCom authentication, synchronization, and notification settings\n- Email management\n- Form drafts\n- Public forms\n- Backup management\n- Data source management\n- Translation testing tools\n\nThis release also fixes a range of issues affecting mobile devices, embedded pages, sub-application SSO, printing, and exporting, further improving the stability and consistency of the V2 entry.\n\nRelated documentation:\n\n## Plugins that no longer support V2 (deprecated but not yet removed)\n\nSome plugins were deprecated in earlier releases. A number of them can still be used for now, but they will be removed entirely in NocoBase 3.\n\n| Plugin | Replacement | Notes |\n|---|---|---|\n`@nocobase/plugin-audit-logs` | `@nocobase/plugin-audit-logger` | Deprecated since 1.0 |\n`@nocobase/plugin-backup-restore` | `@nocobase/plugin-backups` | Deprecated since 1.0 |\n`@nocobase/plugin-block-multi-step-form` | JS Block | Deprecated since 2.0 |\n`@nocobase/plugin-charts` | `@nocobase/plugin-data-visualization` | Deprecated since 2.0 |\n`@nocobase/plugin-collection-fdw` | Database synchronization | Deprecated since 2.2 |\n`@nocobase/plugin-comments` | `@nocobase/plugin-block-comment` | Deprecated since 2.2 |\n`@nocobase/plugin-custom-variables` | Event flow | Deprecated since 2.2 |\n`@nocobase/plugin-data-visualization-echarts` | `@nocobase/plugin-data-visualization` | Deprecated since 2.0 |\n`@nocobase/plugin-disable-pm-add` | None | Deprecated since 2.2 |\n`@nocobase/plugin-field-component-mask` | RunJS | Deprecated since 2.0 |\n`@nocobase/plugin-graph-collection-manager` | None | Deprecated since 2.2 |\n`@nocobase/plugin-mobile-client` | `@nocobase/plugin-ui-layout` | Deprecated since 2.0 |\n`@nocobase/plugin-mobile` | `@nocobase/plugin-ui-layout` | Deprecated since 2.0 |\n`@nocobase/plugin-mock-collections` | AI-powered app building | Deprecated since 2.0 |\n`@nocobase/plugin-multi-app-manager` | `@nocobase/plugin-app-supervisor` | Deprecated since 2.0 |\n`@nocobase/plugin-multi-app-share-collection` | None | Deprecated since 1.0 |\n`@nocobase/plugin-notifications` | `@nocobase/plugin-notification-manager` | Deprecated since 1.0 |\n`@nocobase/plugin-snapshot-field` | None | Deprecated since 1.0 |", "url": "https://wpnews.pro/news/announcing-nocobase-2-2", "canonical_source": "https://www.nocobase.com/en/blog/2.2.0", "published_at": "2026-08-23 14:37:56+00:00", "updated_at": "2026-08-23 15:43:05.070783+00:00", "lang": "en", "topics": ["developer-tools"], "entities": ["NocoBase"], "alternates": {"html": "https://wpnews.pro/news/announcing-nocobase-2-2", "markdown": "https://wpnews.pro/news/announcing-nocobase-2-2.md", "text": "https://wpnews.pro/news/announcing-nocobase-2-2.txt", "jsonld": "https://wpnews.pro/news/announcing-nocobase-2-2.jsonld"}}