create-octane-xplat 0.13.0 → 0.15.0

package/README.md

@@ -16,6 +16,26 @@ With Node.js and pnpm 11.24.0 installed:
 pnpm create octane-xplat my-app
 ```
 
+## Start a library package
+
+To start a reusable package instead of an app, select the library template:
+
+```sh
+pnpm create octane-xplat my-controls --template library
+cd my-controls
+pnpm typecheck
+pnpm typegen
+pnpm test:packed
+```
+
+The library starter publishes source for web, iOS, and Android, which the
+consuming app compiles. It includes conditional exports, generated `.d.ts`
+declarations, lint and unit-test
+scripts, and a packed-consumer check. Pass `--name @acme/my-controls` to set a
+scoped npm package name; otherwise the folder name becomes the package name.
+Library creation installs dependencies but does not start an app dev server.
+Desktop targets are not included in this starter.
+
 The creator asks which platforms to target — web, iOS, and Android are all
 pre-selected. Pass `--targets` to skip the prompt:
 
@@ -59,7 +79,7 @@ From that directory, these commands run other targets or check the app — the
 pnpm dev:ios        # needs macOS, Xcode, and NativeScript setup
 pnpm dev:android    # needs Android SDK, compatible JDK, and NativeScript setup
 pnpm lint
-pnpm typecheck      # every enabled tsconfig
+pnpm typecheck      # tsconfig.json + every declared environment
 pnpm build          # web production bundle
 ```
 

package/index.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { existsSync, readdirSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { basename, resolve } from 'node:path'
 import { spawnSync } from 'node:child_process'
 import {
+	composeLibrary,
 	composeTargets,
 	defaultTargets,
 	resolveTargets,
@@ -12,6 +13,41 @@ import {
 
 const argv = process.argv.slice(2)
 const noInstall = argv.includes('--no-install')
+const templateIndex = argv.findIndex((arg) => arg === '--template' || arg.startsWith('--template='))
+const templateValueIndex =
+	templateIndex !== -1 && argv[templateIndex] === '--template' ? templateIndex + 1 : -1
+
+const templateArg =
+	templateIndex === -1
+		? 'app'
+		: templateValueIndex !== -1
+			? argv[templateValueIndex]
+			: argv[templateIndex].slice('--template='.length)
+
+const nameIndex = argv.findIndex((arg) => arg === '--name' || arg.startsWith('--name='))
+const nameValueIndex = nameIndex !== -1 && argv[nameIndex] === '--name' ? nameIndex + 1 : -1
+const nameArg =
+	nameIndex === -1
+		? undefined
+		: nameValueIndex !== -1
+			? argv[nameValueIndex]
+			: argv[nameIndex].slice('--name='.length)
+
+if (templateIndex !== -1 && (!templateArg || templateArg.startsWith('-'))) {
+	console.error('✗ --template needs a value: app or library')
+	process.exit(1)
+}
+
+if (!['app', 'library'].includes(templateArg)) {
+	console.error(`✗ unknown template "${templateArg}" — expected app or library`)
+	process.exit(1)
+}
+
+if (nameIndex !== -1 && (!nameArg || nameArg.startsWith('-'))) {
+	console.error('✗ --name needs an npm package name')
+	process.exit(1)
+}
+
 const targetsIndex = argv.findIndex((arg) => arg === '--targets' || arg.startsWith('--targets='))
 const targetsValueIndex =
 	targetsIndex !== -1 && argv[targetsIndex] === '--targets' ? targetsIndex + 1 : -1
@@ -28,8 +64,26 @@ if (targetsIndex !== -1 && (targetsArg === undefined || targetsArg.startsWith('-
 	process.exit(1)
 }
 
-const positional = argv.filter((arg, i) => !arg.startsWith('-') && i !== targetsValueIndex)
-const dir = resolve(positional[0] ?? 'octane-xplat-app')
+const optionValues = new Set(
+	[targetsValueIndex, templateValueIndex, nameValueIndex].filter((index) => index !== -1),
+)
+
+const positional = argv.filter((arg, i) => !arg.startsWith('-') && !optionValues.has(i))
+const defaultDir = templateArg === 'library' ? 'octane-xplat-library' : 'octane-xplat-app'
+const dir = resolve(positional[0] ?? defaultDir)
+
+if (templateArg === 'library' && targetsIndex !== -1) {
+	console.error(
+		'✗ --targets applies to the app template; libraries start with web and native builds',
+	)
+
+	process.exit(1)
+}
+
+if (templateArg === 'app' && nameIndex !== -1) {
+	console.error('✗ --name applies only to the library template')
+	process.exit(1)
+}
 
 if (existsSync(dir) && readdirSync(dir).length > 0) {
 	console.error(`✗ ${dir} exists and is not empty`)
@@ -57,69 +111,85 @@ const parseTargets = (value) => {
 	return resolveTargets(ids)
 }
 
-let ids
-if (targetsArg !== undefined) {
+let ids = []
+if (templateArg === 'library') {
+	const packageName = nameArg ?? basename(dir)
 	try {
-		ids = parseTargets(targetsArg)
+		composeLibrary(dir, packageName)
 	} catch (error) {
 		console.error(`✗ ${error.message}`)
 		process.exit(1)
 	}
-} else if (process.stdout.isTTY) {
-	// Lazy: the extracted tarball has no installed deps — only the interactive
-	// path needs @clack/prompts (verify-consumer runs the bin dep-free).
-	const p = await import('@clack/prompts')
-	p.intro('create-octane-xplat')
-	const picked = await p.multiselect({
-		message: 'Target platforms',
-		options: selectableTargets.map((id) => ({
-			value: id,
-			label: targets[id].label,
-			hint: targets[id].note,
-		})),
-		initialValues: [...defaultTargets],
-		required: true,
-	})
-
-	if (p.isCancel(picked)) {
-		p.cancel('Cancelled')
-		process.exit(0)
-	}
 
-	ids = picked
+	console.log(`\n✓ scaffolded ${dir} (library: ${packageName}; web + iOS + Android)`)
 } else {
-	ids = defaultTargets
-}
+	if (targetsArg !== undefined) {
+		try {
+			ids = parseTargets(targetsArg)
+		} catch (error) {
+			console.error(`✗ ${error.message}`)
+			process.exit(1)
+		}
+	} else if (process.stdout.isTTY) {
+		// Lazy: the extracted tarball has no installed deps — only the interactive
+		// path needs @clack/prompts (verify-consumer runs the bin dep-free).
+		const p = await import('@clack/prompts')
+		p.intro('create-octane-xplat')
+		const picked = await p.multiselect({
+			message: 'Target platforms',
+			options: selectableTargets.map((id) => ({
+				value: id,
+				label: targets[id].label,
+				hint: targets[id].note,
+			})),
+			initialValues: [...defaultTargets],
+			required: true,
+		})
+
+		if (p.isCancel(picked)) {
+			p.cancel('Cancelled')
+			process.exit(0)
+		}
 
-composeTargets(ids, dir)
+		ids = picked
+	} else {
+		ids = defaultTargets
+	}
 
-console.log(
-	`\n✓ scaffolded ${dir} (${[...new Set(resolveTargets(ids))].filter((id) => !targets[id].hidden).join(', ')})`,
-)
+	composeTargets(ids, dir)
+	console.log(
+		`\n✓ scaffolded ${dir} (${[...new Set(resolveTargets(ids))].filter((id) => !targets[id].hidden).join(', ')})`,
+	)
+}
 
 if (noInstall) {
 	console.log('\nSkipped install (--no-install). To run manually:')
-	printNextSteps(dir, ids)
+	printNextSteps(dir, ids, templateArg)
 	process.exit(0)
 }
 
 const install = spawnSync('pnpm', ['install'], { cwd: dir, stdio: 'inherit' })
 if (install.status !== 0) {
 	console.log(`\nInstall didn't finish (pnpm missing?). To run manually:`)
-	printNextSteps(dir, ids)
+	printNextSteps(dir, ids, templateArg)
 	process.exit(install.status ?? 1)
 }
 
-if (ids.includes('web')) {
+if (templateArg === 'app' && ids.includes('web')) {
 	console.log('\n✓ installed — starting dev server (Ctrl+C to stop)\n')
 	spawnSync('pnpm', ['dev'], { cwd: dir, stdio: 'inherit' })
 } else {
-	console.log('\n✓ installed. To run:')
-	printNextSteps(dir, ids)
+	console.log('\n✓ installed. Next steps:')
+	printNextSteps(dir, ids, templateArg)
 }
 
-function printNextSteps(dir, ids) {
+function printNextSteps(dir, ids, template) {
 	console.log(`  cd ${dir}\n  pnpm install`)
+	if (template === 'library') {
+		console.log('  pnpm typecheck\n  pnpm lint\n  pnpm typegen\n  pnpm test\n  pnpm test:packed')
+		return
+	}
+
 	if (ids.includes('web')) {
 		console.log('  pnpm dev')
 	} else {

package/library-template/.oxlintrc.json

@@ -0,0 +1,24 @@
+{
+	"jsPlugins": ["@octane-xplat/lint/oxlint-plugin"],
+	"rules": {
+		"curly": "error",
+		"xplat/no-dom-globals": "error",
+		"xplat/no-web-only-api": "error",
+		"xplat/element-vocabulary": "error",
+		"xplat/no-nativescript-import": "error",
+		"xplat/no-ns-deep-import": "error",
+		"xplat/no-native-dead-style": "error",
+		"xplat/no-line-height-unitless": "error",
+		"xplat/no-style-string": "error",
+		"xplat/no-unknown-class": "warn",
+		"xplat/no-ts-imports-tsrx": "error",
+		"xplat/signal-dollar-suffix": "error",
+		"xplat/require-signals-runtime": "warn",
+		"xplat/no-view-onpress": "error",
+		"xplat/no-console-debug": "error",
+		"xplat/hooks-in-plain-ts": "warn",
+		"xplat/native-pragma-first-line": "error",
+		"xplat/no-jsx-text-breakers": "error",
+		"xplat/no-root-logical-render": "error"
+	}
+}

package/library-template/AGENTS.md

@@ -0,0 +1,16 @@
+# Library package notes
+
+- Use pnpm for package management.
+- Keep the public API in `src/index.ts` and `src/index.web.ts`; both barrels
+  must export the same names and types.
+- Put shared prop contracts in `src/props.ts` and document public exports.
+- The unsuffixed `.tsx` file is the NativeScript implementation. Add a
+  `.web.tsx` sibling when browser behavior or markup needs to differ. Native
+  files start with `/** @jsxImportSource @nativescript-community/octane */`.
+- Keep DOM globals out of native files. Use the shared `@octane-xplat/ui`
+  elements when behavior can be shared.
+- Declare every imported package. Runtime plugins belong in `dependencies`;
+  Octane and renderer packages belong in `peerDependencies` when consumers
+  supply the runtime.
+- Before publishing, run `pnpm typecheck`, `pnpm lint`, `pnpm test`,
+  `pnpm typegen`, and `pnpm test:packed`.

package/{LICENSE → library-template/LICENSE}

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2026 Alec Larson
+Copyright (c) [year] [copyright holder]
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/library-template/README.md

@@ -0,0 +1,64 @@
+# octane-xplat-library
+
+A cross-platform component library for Octane Xplat. The starter includes a
+small `Badge` component and a packed-consumer check so you can build a package
+and check the artifact that will be published.
+
+## Start here
+
+Install this package in an Octane Xplat app:
+
+```sh
+pnpm add octane-xplat-library
+```
+
+Render the example component from your app:
+
+```tsx
+import { Badge } from 'octane-xplat-library'
+
+export function Welcome() {
+	return <Badge label="Ready" />
+}
+```
+
+## Develop and check
+
+Run these commands from the package directory:
+
+```sh
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm typegen
+pnpm test:packed
+```
+
+The package publishes authored source for the app's bundler to compile.
+`pnpm typegen` generates `.d.ts` files so consumers' type checkers use
+declarations. `pnpm test:packed` packs the package, places that artifact into
+small web and native TypeScript consumers, and checks both export conditions.
+
+The package sets `nodeLinker: hoisted` in `pnpm-workspace.yaml` because the
+NativeScript bundler expects a flat dependency tree.
+
+## Platform files
+
+`src/Badge.tsx` is the shared iOS and Android implementation. The
+`src/Badge.web.tsx` sibling supplies the web implementation. Keep their props
+and exports aligned in `src/props.ts` and the two `src/index` barrels. Add
+`.ios.tsx`, `.android.tsx`, or `.mobile.tsx` files only when a behavior needs
+to differ on those targets.
+
+The starter supports web, iOS, and Android. It does not include app shells or
+desktop runtime entries. If the package uses a NativeScript plugin, declare it
+as a runtime dependency and add the plugin's required platform files and
+metadata to this package.
+
+## Prepare to publish
+
+Before publishing, replace the generated package name and repository metadata
+in `package.json`, fill in the year and copyright holder in `LICENSE`, and
+confirm that every runtime import is declared. `pnpm test:packed` checks the
+package tarball's web and native type exports; it does not build or launch a
+consuming app on a device.

package/library-template/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+types/
+coverage/
+.turbo/

package/library-template/package.json

@@ -0,0 +1,89 @@
+{
+	"name": "octane-xplat-library",
+	"version": "0.1.0",
+	"description": "A cross-platform component library for Octane Xplat",
+	"keywords": [
+		"android",
+		"cross-platform",
+		"ios",
+		"octane",
+		"octane-xplat",
+		"ui",
+		"web"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/your-org/your-library",
+		"directory": "."
+	},
+	"files": [
+		"src",
+		"types",
+		"LICENSE"
+	],
+	"type": "module",
+	"exports": {
+		".": {
+			"macos": null,
+			"linux": null,
+			"windows": null,
+			"web": {
+				"types": "./types/index.web.d.ts",
+				"default": "./src/index.web.ts"
+			},
+			"native": {
+				"types": "./types/index.d.ts",
+				"default": "./src/index.ts"
+			},
+			"types": "./types/index.d.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"typegen": "tsrx-typegen --project tsconfig.types.json",
+		"typecheck": "xplat typecheck",
+		"lint": "xplat-lint",
+		"lint:fix": "xplat-lint --fix",
+		"test": "vitest run",
+		"test:packed": "node tests/packed-consumer.mjs",
+		"prepack": "pnpm typegen && tsrx-typegen --pack-check",
+		"pack:check": "pnpm test:packed",
+		"format": "xplat fmt"
+	},
+	"devDependencies": {
+		"@nativescript-community/octane": "catalog:",
+		"@nativescript/core": "catalog:",
+		"@nativescript/types": "catalog:",
+		"@octane-xplat/cli": "^0.15.0",
+		"@octane-xplat/lint": "^0.15.0",
+		"@octane-xplat/ui": "^0.15.0",
+		"@octanejs/vite-plugin": "catalog:",
+		"@tsrx/oxc": "0.20.0",
+		"@tsrx/typescript-plugin": "catalog:",
+		"octane": "catalog:",
+		"oxlint": "^1.74.0",
+		"tsrx-typegen": "^0.2.2",
+		"typescript": "catalog:",
+		"vite": "catalog:",
+		"vitest": "catalog:"
+	},
+	"peerDependencies": {
+		"@nativescript-community/octane": ">=0.2.1 <1",
+		"@nativescript/core": ">=9.1.0 <10",
+		"@octane-xplat/ui": "^0.15.0",
+		"octane": ">=0.6.3 <1"
+	},
+	"peerDependenciesMeta": {
+		"@nativescript-community/octane": {
+			"optional": true
+		},
+		"@nativescript/core": {
+			"optional": true
+		}
+	},
+	"packageManager": "pnpm@11.24.0"
+}

package/library-template/pnpm-workspace.yaml

@@ -0,0 +1,17 @@
+# NativeScript's bundler resolves dependencies from the flat package tree.
+nodeLinker: hoisted
+allowBuilds:
+  esbuild: true
+  '@parcel/watcher': true
+  '@nativescript/core': false
+# Shared version pins — bump these here, every dependency field reads them.
+catalog:
+  octane: 0.11.0
+  '@nativescript-community/octane': 0.2.4
+  '@nativescript/core': 9.1.3
+  '@nativescript/types': 9.1.4
+  typescript: 5.9.3
+  vite: 8.3.0
+  '@octanejs/vite-plugin': 0.1.61
+  '@tsrx/typescript-plugin': 0.4.11
+  vitest: 4.1.11

package/library-template/src/Badge.tsx

@@ -0,0 +1,21 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { Text, View } from '@octane-xplat/ui'
+import { normalizeBadgeLabel } from './normalizeBadgeLabel'
+import type { BadgeProps } from './props'
+
+/**
+ * Render a short label using Octane's NativeScript elements.
+ * @example
+ * ```tsx
+ * import { Badge } from 'octane-xplat-library'
+ *
+ * <Badge label="Ready" />
+ * ```
+ */
+export function Badge(props: BadgeProps) {
+	return (
+		<View className={props.className}>
+			<Text>{normalizeBadgeLabel(props.label)}</Text>
+		</View>
+	)
+}

package/library-template/src/Badge.web.tsx

@@ -0,0 +1,21 @@
+/** @jsxImportSource octane */
+import { Text, View } from '@octane-xplat/ui'
+import { normalizeBadgeLabel } from './normalizeBadgeLabel'
+import type { BadgeProps } from './props'
+
+/**
+ * Render a short label using Octane's web elements.
+ * @example
+ * ```tsx
+ * import { Badge } from 'octane-xplat-library'
+ *
+ * <Badge label="Ready" />
+ * ```
+ */
+export function Badge(props: BadgeProps) {
+	return (
+		<View className={props.className}>
+			<Text>{normalizeBadgeLabel(props.label)}</Text>
+		</View>
+	)
+}

package/library-template/src/index.ts

@@ -0,0 +1,3 @@
+export { Badge } from './Badge'
+export { normalizeBadgeLabel } from './normalizeBadgeLabel'
+export type { BadgeProps } from './props'

package/library-template/src/index.web.ts

@@ -0,0 +1,3 @@
+export { Badge } from './Badge'
+export { normalizeBadgeLabel } from './normalizeBadgeLabel'
+export type { BadgeProps } from './props'

package/library-template/src/normalizeBadgeLabel.ts

@@ -0,0 +1,12 @@
+/**
+ * Trim surrounding whitespace from a badge label.
+ * @example
+ * ```ts
+ * import { normalizeBadgeLabel } from 'octane-xplat-library'
+ *
+ * normalizeBadgeLabel('  Ready  ')
+ * ```
+ */
+export function normalizeBadgeLabel(label: string): string {
+	return label.trim()
+}

package/library-template/src/props.ts

@@ -0,0 +1,14 @@
+/** Props for the starter badge component. */
+export interface BadgeProps {
+	/** Text displayed inside the badge.
+	 * @example
+	 * ```tsx
+	 * import { Badge } from 'octane-xplat-library'
+	 *
+	 * <Badge label="Ready" />
+	 * ```
+	 */
+	label: string
+	/** Optional class name forwarded to the outer view. */
+	className?: string
+}

package/library-template/tests/normalizeBadgeLabel.test.ts

@@ -0,0 +1,6 @@
+import { expect, it } from 'vitest'
+import { normalizeBadgeLabel } from '../src/normalizeBadgeLabel'
+
+it('trims surrounding whitespace from a badge label', () => {
+	expect(normalizeBadgeLabel('  Ready  ')).toBe('Ready')
+})