@nocobase/portal-template-default 1.0.9 → 1.0.10

package/.env.example

@@ -6,5 +6,10 @@ NOCOBASE_AUTHENTICATOR=basic
 # Use / for root-local development, or /x/admin/ when building for storage/dist-client/x/admin.
 NOCOBASE_PORTAL_BASE=/x/admin/
 
+# Keep these aligned with the main NocoBase frontend when customized.
+# API_CLIENT_STORAGE_PREFIX=NOCOBASE_
+# API_CLIENT_STORAGE_TYPE=localStorage
+# API_CLIENT_SHARE_TOKEN=false
+
 # Optional for local development. Do not commit real access tokens.
 # NOCOBASE_API_TOKEN=

package/.github/workflows/publish.yml

@@ -0,0 +1,106 @@
+name: Publish npm package
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Exact version (leave blank to increment patch)
+        required: false
+        type: string
+      tag:
+        description: npm distribution tag
+        required: true
+        default: latest
+        type: choice
+        options:
+          - latest
+          - next
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: publish-npm-package
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          run_install: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+          registry-url: https://registry.npmjs.org
+
+      - name: Update npm
+        run: npm install -g npm@latest
+
+      - name: Print tool versions
+        run: |
+          node --version
+          npm --version
+          pnpm --version
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Resolve release version
+        id: release
+        env:
+          REF_TYPE: ${{ github.ref_type }}
+          REQUESTED_VERSION: ${{ inputs.version }}
+        run: |
+          if [ "$REF_TYPE" != "branch" ]; then
+            echo "Run this workflow from a branch, not a tag."
+            exit 1
+          fi
+
+          if [ -n "$REQUESTED_VERSION" ]; then
+            npm version "$REQUESTED_VERSION" --no-git-tag-version
+          else
+            npm version patch --no-git-tag-version
+          fi
+
+          VERSION=$(node -p "require('./package.json').version")
+          if git rev-parse --verify --quiet "refs/tags/v${VERSION}"; then
+            echo "Git tag v${VERSION} already exists."
+            exit 1
+          fi
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+
+      - name: Materialize default extensions
+        run: node scripts/registry.mjs materialize
+
+      - name: Inspect package
+        run: npm pack --dry-run
+
+      - name: Build
+        run: pnpm build
+
+      - name: Publish package
+        run: npm publish --access public --tag "${{ inputs.tag }}" --loglevel verbose
+
+      - name: Commit and tag release
+        env:
+          TARGET_BRANCH: ${{ github.ref_name }}
+          VERSION: ${{ steps.release.outputs.version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add package.json
+          git commit -m "chore(release): v${VERSION}"
+          git tag -a "v${VERSION}" -m "v${VERSION}"
+          git push --atomic origin "HEAD:refs/heads/${TARGET_BRANCH}" "refs/tags/v${VERSION}"

package/.gitignore

@@ -0,0 +1,33 @@
+# Logs
+
+logs
+_.log
+npm-debug.log_
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+/.extension-state/
+/registry.json
+/public/r/
+
+# Environment variables
+.env
+.env.local
+
+# Editor directories and files
+
+.vscode/_
+!.vscode/extensions.json
+.idea
+.DS_Store
+_.suo
+_.ntvs_
+_.njsproj
+_.sln
+\*.sw?

package/AGENTS.md

@@ -0,0 +1,19 @@
+# Application Development Guidelines
+
+This repository is a starter for building a NocoBase-powered application. Keep changes focused on the application being built and follow these guidelines before introducing new abstractions.
+
+## Reuse existing extensions
+
+Before writing new code, inspect `registry` in the Registry source repository or `src/extensions` in a published template for similar pages, hooks, components, and integration patterns. Reuse an existing implementation directly when it already fits the requirement, and extend or compose it when only a small adaptation is needed.
+
+## Customize UI components through composition
+
+Treat `src/components/ui` as the project's shadcn/ui foundation. When application-specific behavior or styling is needed, prefer wrapping, pre-composing, or re-exporting the base component from a feature-level component instead of editing the base component directly. This keeps the base components replaceable and makes future updates easier to review.
+
+Components copied from shadcn/ui are owned and maintained by this project; upstream changes are not applied automatically. If a base component must be changed or updated, compare it with the upstream version first, then selectively merge bug fixes and improvements while preserving intentional local behavior. Do not blindly overwrite customized components.
+
+## Develop Portal Registry items
+
+Canonical NocoBase Registry source lives under `registry/`. In this source repository, normal development and builds load it directly; do not copy it into `src/extensions` for preview. Imports from a Registry item to the host application must use the `@/` alias. Relative imports must stay within that Registry item's own root so the item remains portable after installation. Registry items target this Portal Template's React, shadcn Base UI, and pnpm toolchain. They must never import Ant Design or NocoBase's Ant Design-based client components.
+
+Keep Registry items portable and focused on reusable API adapters, hooks, components, and small demos. Update `registry.config.json` whenever an item's files, dependencies, or installation target changes. Validate Registry changes with the normal application build and the relevant regression scripts.

package/README.MD

@@ -1,220 +1,101 @@
-# nocobase-admin-starter
+# NocoBase Portal Template
 
-![2026-07-22-08-48-12](https://static-docs.nocobase.com/2026-07-22-08-48-12.png)
+A React and shadcn/ui template for building standalone frontends backed by
+NocoBase.
 
-## NocoBase configuration
+![NocoBase Portal Template](https://static-docs.nocobase.com/2026-07-22-08-48-12.png)
 
-Copy `.env.example` to `.env.local` and set the NocoBase API URL. The default `basic` authenticator uses the NocoBase username or email and password login. For local development, a temporary access token can be supplied through `NOCOBASE_API_TOKEN`; do not commit it. The data provider sends it as `Authorization: Bearer <token>`.
-
-If you call a remote NocoBase instance from `http://localhost:*`, the browser may block `auth:signIn` because NocoBase requires the `X-Authenticator` request header and the remote server must explicitly allow it in CORS preflight responses. In local Vite development, prefer using the built-in dev proxy:
-
-```env
-NOCOBASE_API_URL=https://develop.v2.test.nocobase.com/nocobase/api/__app/cms
-```
-
-In development, the app auto-detects the proxy target from `NOCOBASE_API_URL` when that value is an absolute URL. The configured API URL can stay on the original sub-app path such as `/nocobase/api/__app/cms`.
-
-Application resource names must match NocoBase collection names. The included
-Users example targets the default `users` collection, so it works without a
-project-specific business collection.
-
-Application-owned React translations live in `src/locales`. The entry registers
-an `app` namespace for business pages and augments the default `starter`
-namespace for shared controls. Feature-specific Registry translations remain
-inside their own extension namespace and are not mixed into application locale
-files.
-
-### Authentication UI
-
-The default login page calls `authenticators:publicList` and renders every
-enabled NocoBase authenticator that has a frontend adapter installed. Basic
-username/password authentication is built into the Starter. Optional methods
-are installed independently:
+## Quick start
 
 ```bash
-pnpm exec shadcn add @nocobase/auth-sms
-pnpm exec shadcn add @nocobase/auth-ldap
-pnpm exec shadcn add @nocobase/auth-oidc
-pnpm exec shadcn add @nocobase/auth-saml
-pnpm exec shadcn add @nocobase/auth-cas
-pnpm exec shadcn add @nocobase/auth-wecom
-pnpm exec shadcn add @nocobase/auth-dingtalk
+pnpm install
+cp .env.example .env.local
+pnpm dev
 ```
 
-The Starter includes an Authentication Demo for the three customization
-boundaries below. Each optional authentication Registry adds its own component
-Demo under the same Authentication menu when installed.
+The development server starts at `http://localhost:5173` by default.
 
-The application login page remains the customization boundary. Keep the
-default dynamic page with:
+## Configuration
 
-```tsx
-import { DefaultSignInPage } from "@/components/auth/default-sign-in-page"
+The minimum local configuration is:
 
-export const Login = () => <DefaultSignInPage />
+```env
+NOCOBASE_API_URL=/api
+NOCOBASE_PORTAL_BASE=/
 ```
 
-To replace only one authenticator UI, use `renderAuthenticator` and return the
-default element for everything else:
-
-```tsx
-import { DefaultSignInPage } from "@/components/auth/default-sign-in-page"
-import { useOidcSignIn } from "@/extensions/nocobase-auth-oidc"
-import { Button } from "@/components/ui/button"
-
-function CompanyOidcButton({ authenticator }) {
-  const oidc = useOidcSignIn(authenticator)
-  return <Button onClick={oidc.signIn}>Company SSO</Button>
-}
-
-export const Login = () => (
-  <DefaultSignInPage
-    renderAuthenticator={({ authenticator, defaultElement }) =>
-      authenticator.name === "company-oidc" ? (
-        <CompanyOidcButton authenticator={authenticator} />
-      ) : (
-        defaultElement
-      )
-    }
-  />
-)
-```
+- `NOCOBASE_API_URL` is the NocoBase REST API root and must include `/api`.
+  Same-origin deployments normally use `/api`. During local development, an
+  absolute URL is handled through the Vite proxy.
+- `NOCOBASE_PORTAL_BASE` is the public path where the Portal is mounted. Use
+  `/` for root development or set the deployment path before building.
+- `NOCOBASE_API_TOKEN` can provide a temporary development token. Never commit
+  real tokens.
 
-Replace `src/pages/login/index.tsx` completely when the application needs a
-fully custom login page. Token callback capture, current authenticator storage,
-request headers, and logout behavior remain provided by the Starter runtime and
-do not depend on `DefaultSignInPage`.
-
-```tsx
-import { AuthLayout } from "@/components/auth/auth-layout"
-import { BasicSignInForm } from "@/components/auth"
-
-export const Login = () => (
-  <AuthLayout title="Sign in" description="Continue to your workspace.">
-    <BasicSignInForm
-      authenticator={{
-        name: "basic",
-        authType: "Email/Password",
-      }}
-    />
-  </AuthLayout>
-)
-```
+The Portal uses the same authentication storage convention as NocoBase. If the
+server customizes it, keep `API_CLIENT_STORAGE_PREFIX`,
+`API_CLIENT_STORAGE_TYPE`, and `API_CLIENT_SHARE_TOKEN` aligned with the server.
 
-## Available Scripts
-
-### Running the development server.
+## Development
 
 ```bash
+# Start the Vite development server
 pnpm dev
-```
 
-### Building for production.
-
-```bash
+# Build the production assets
 pnpm build
-```
-
-### Extensions and the NocoBase Shadcn Registry
-
-The starter separates framework-owned extension support from installed Registry
-source:
 
-- `src/app/extension.ts` defines the generic extension contract.
-- `src/app/extensions.tsx` discovers `src/extensions/*/extension.tsx` and adds
-  its providers, Refine resources, and routes to the app.
-- `registry/<name>` contains the canonical authoring source for a Registry
-  package while it is developed in this repository.
-- `src/extensions/<name>` contains installed, application-owned source.
-  Downstream applications can commit this directory like any other source code.
-
-`registry.config.json` is the only authoring manifest. In addition to standard
-Shadcn Registry item fields, each item has a local `source` mapping used to
-generate its standard `files` array. The same mapping lets the starter's
-`postinstall` hook copy a locally authored extension only when its target is
-missing. Existing installed source is never compared, updated, or overwritten.
-Optional entries can set `source.install` to `false`; they remain available to
-Registry builds and local previews but are not added by `postinstall`.
-
-You can run the same missing-only installation explicitly with:
-
-```bash
-pnpm registry:install
-```
-
-This repository authors optional NocoBase integration entries. Internationalization
-is delivered as one cohesive Registry entry:
-
-- `i18n` extends the Starter's built-in translation provider and shared System
-  Settings bootstrap with selected server-generated namespaces such as
-  `lm-collections`, user locale persistence, the language switcher, and the
-  lazy-loaded showcase with its prompt generator.
-
-The AI integration is available through four incremental entries:
-
-- `ai-runtime` provides AI services, providers, transports, and
-  controllers. Its NocoBase requests use the starter's shared
-  `src/lib/nocobase/client.ts` client.
-- `ai-chat` adds the reusable chat components and depends on the
-  runtime entry.
-- `ai-react-hook-form` adds the optional React Hook Form adapter for the fixed
-  Form filler Tool.
-- `ai` adds the application extension integration and Demo pages and depends on the
-  chat entry.
-
-To refresh the local preview from the canonical Registry source, run:
+# Serve a production build
+pnpm start
 
-```bash
-pnpm registry:preview
+# Build a standalone HTML artifact
+pnpm build:html
 ```
 
-This is the only command that intentionally replaces the local preview at
-`src/extensions/nocobase-ai`. Normal `pnpm dev`, `pnpm install`, and
-`pnpm registry:install` do not overwrite an installed extension.
+Application pages and resources live under `src`. The included Users page is a
+working example based on the standard NocoBase `users` collection.
 
-Build the standard Shadcn Registry JSON files into `public/r` with:
+Application translations live in `src/locales`. Shared UI components live in
+`src/components/ui` and follow the shadcn Base UI conventions.
 
-```bash
-pnpm registry:build
-```
+## Extensions
 
-With the development server running, a compatible starter can also add the
-complete item through Shadcn:
+Installed extensions live in `src/extensions` and are ordinary
+application-owned source files. Their providers, resources, routes, login
+adapters, and user-menu items are discovered automatically.
 
-```bash
-pnpm dlx shadcn@latest add @nocobase/ai
-```
+Optional NocoBase integrations, including authentication methods and i18n, can
+be installed from the `@nocobase` Registry configured in `components.json`.
+After installation, the generated source can be customized and committed with
+the application.
 
-Install the optional NocoBase i18n integration with:
+In this Registry source repository, canonical extension source lives in
+`registry` and is loaded directly by `pnpm dev` and `pnpm build`. The published
+npm template contains the default extensions under `src/extensions` instead.
 
-```bash
-pnpm dlx shadcn@latest add @nocobase/i18n
-```
+## Authentication
 
-Shadcn does not keep a Registry item lock or merge local changes. Re-running
-`add` downloads the current item, skips identical files, and asks before
-replacing different files. Use `--diff` to inspect an update and `--overwrite`
-to accept the Registry version explicitly.
+Basic username or email and password login is built in. The default login page
+also renders enabled NocoBase authentication methods when their frontend
+Registry adapters are installed.
 
-The Registry alias is configured in `components.json` and resolves to
-`http://localhost:5173/r/{name}.json` during local development. The same generic
-extension host and Registry source mapping can be reused for future Registry
-packages without adding package-specific logic to `App.tsx` or the installer.
+Customize `src/pages/login/index.tsx` to replace the whole login page, or use
+`DefaultSignInPage` to keep dynamic authentication while overriding individual
+authenticator UI.
 
-### Running the production server.
+## Tests
 
 ```bash
-pnpm start
+pnpm test:auth
+pnpm test:acl
+pnpm test:i18n
 ```
 
-## Learn More
-
-To learn more about **Refine**, please check out the [Documentation](https://refine.dev/docs)
+## Learn more
 
-- **REST Data Provider** [Docs](https://refine.dev/docs/core/providers/data-provider/#overview)
-- **shadcn/ui** [Docs](https://refine.dev/docs/guides-concepts/general-concepts/#headless-concept)
-- **React Router** [Docs](https://refine.dev/docs/core/providers/router-provider/)
-- **Custom Auth Provider** [Docs](https://refine.dev/docs/core/providers/auth-provider/)
+- [NocoBase documentation](https://docs.nocobase.com/)
+- [Refine documentation](https://refine.dev/docs/)
+- [shadcn/ui documentation](https://ui.shadcn.com/)
 
 ## License
 

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@nocobase/portal-template-default",
-  "version": "1.0.9",
+  "version": "1.0.10",
+  "packageManager": "pnpm@10.28.0",
   "type": "module",
   "devDependencies": {
     "@ai-sdk/react": "2.0.0",
@@ -77,13 +78,10 @@
     "url": "git+https://github.com/nocobase/portal-template-default.git"
   },
   "scripts": {
-    "postinstall": "node ./scripts/registry.mjs install-missing",
     "dev": "vite",
     "build": "tsc && refine build",
     "build:html": "node ./scripts/build-html.mjs",
-    "registry:install": "node ./scripts/registry.mjs install-missing",
-    "registry:preview": "node ./scripts/registry.mjs preview",
-    "registry:build": "node ./scripts/registry.mjs build && shadcn build ./registry.json -o ./public/r",
+    "test:auth": "node tests/auth-session-regression.mjs",
     "test:acl": "node registry/nocobase-acl/tests/acl-regression.mjs",
     "test:i18n": "node registry/nocobase-i18n/tests/i18n-regression.mjs",
     "start": "refine start",

package/scripts/build-html.mjs

@@ -65,6 +65,15 @@ const stripExistingRuntimeConfig = (html) => {
 
 const portalBase = normalizePortalBase(process.env.NOCOBASE_PORTAL_BASE);
 const apiUrl = String(process.env.NOCOBASE_API_URL || "/api").trim() || "/api";
+const storagePrefix =
+  String(process.env.API_CLIENT_STORAGE_PREFIX || "NOCOBASE_").trim() ||
+  "NOCOBASE_";
+const storageType =
+  String(process.env.API_CLIENT_STORAGE_TYPE || "localStorage").trim() ||
+  "localStorage";
+const shareToken = /^true$/i.test(
+  String(process.env.API_CLIENT_SHARE_TOKEN || "false").trim()
+);
 
 if (!fs.existsSync(rawIndexPath)) {
   throw new Error(
@@ -76,6 +85,9 @@ const runtimeConfig = `${startMarker}
 <script>
   window.NOCOBASE_PORTAL_BASE = ${JSON.stringify(portalBase)};
   window.NOCOBASE_API_URL = ${JSON.stringify(apiUrl)};
+  window.__nocobase_api_client_storage_prefix__ = ${JSON.stringify(storagePrefix)};
+  window.__nocobase_api_client_storage_type__ = ${JSON.stringify(storageType)};
+  window.__nocobase_api_client_share_token__ = ${JSON.stringify(shareToken)};
 </script>
 ${endMarker}
 `;

package/src/App.css

@@ -1,6 +1,8 @@
 @import "tailwindcss";
 @import "tw-animate-css";
 @import "shadcn/tailwind.css";
+@source "./extensions";
+@source "../registry";
 
 @custom-variant dark (&:is(.dark *));