basic-composables

A collection of basic composables for Vue 3 projects.

Table of Contents

• Breaking Change (Package Rename)
• Installation
• Usage
• Available Composables
• Recommended IDE Setup
• Development
• Publishing to npm
• Build troubleshooting (Yarn)
• License

Breaking Change (Package Rename)

This package was renamed from basic-composables to @scoutkirkolson/basic-composables.

If your existing project used the old name, update it:

yalc remove basic-composables
yalc add @scoutkirkolson/basic-composables
corepack yarn install

And replace imports:

// old
import { useArray, useDate, useString } from 'basic-composables'

// new
import { useArray, useDate, useString } from '@scoutkirkolson/basic-composables'

Temporary compatibility option for production installs:

{
	"dependencies": {
		"basic-composables": "npm:@scoutkirkolson/[email protected]"
	}
}

Installation

Contributor note: local development commands in this repository assume corepack yarn ....

npm install @scoutkirkolson/basic-composables
# or
yarn add @scoutkirkolson/basic-composables

Usage

import { useArray, useDate, useString } from '@scoutkirkolson/basic-composables'

Migration from basic-composables imports

If existing projects still use:

import { useArray, useDate, useString } from 'basic-composables'

you have two options:

1. Recommended: migrate imports to @scoutkirkolson/basic-composables.
2. Compatibility alias (production): keep old import path by aliasing in package.json:

{
	"dependencies": {
		"basic-composables": "npm:@scoutkirkolson/[email protected]"
	}
}

Then your existing imports from 'basic-composables' continue to work.

For local yalc development, prefer migrating imports to the scoped name (@scoutkirkolson/basic-composables) for the most reliable behavior.

Quick migration (consumer project):

# preview matches
grep -R "from 'basic-composables'\\|from \"basic-composables\"" src

# replace imports (GNU sed)
find src -type f \( -name "*.js" -o -name "*.ts" -o -name "*.vue" \) \
	-exec sed -i "s/from 'basic-composables'/from '@scoutkirkolson\\/basic-composables'/g; s/from \"basic-composables\"/from \"@scoutkirkolson\\/basic-composables\"/g" {} +

VS Code migration (Find in Files with regex enabled):

• Find: from\s+['"]basic-composables['"]
• Replace: from '@scoutkirkolson/basic-composables'
• Files to include: src/**/*.{js,ts,vue}

Windows PowerShell migration (consumer project):

# preview matches
Get-ChildItem -Path src -Recurse -File -Include *.js,*.ts,*.vue |
	Select-String -Pattern "from\s+['\"]basic-composables['\"]"

# replace imports
Get-ChildItem -Path src -Recurse -File -Include *.js,*.ts,*.vue | ForEach-Object {
	$content = Get-Content $_.FullName -Raw
	$updated = $content -replace "from\s+'basic-composables'", "from '@scoutkirkolson/basic-composables'"
	$updated = $updated -replace 'from\s+"basic-composables"', 'from "@scoutkirkolson/basic-composables"'
	if ($updated -ne $content) { Set-Content $_.FullName $updated }
}

Available Composables

| Composable | Description | |---|---| | useArray | Array utilities | | useBrowser | Browser/environment utilities | | useBusy | Busy/loading state management | | useCaching | Caching helpers | | useCompare | Comparison utilities | | useDate | Date formatting and manipulation (uses moment.js) | | useDialog | Dialog state management | | useEmbedded | Embedded context helpers | | useFilter | List filtering utilities | | useLoading | Loading state management | | useLocale | Locale/i18n helpers | | useObject | Object utilities | | usePagination | Pagination helpers | | useSaving | Save state management | | useString | String utilities | | useUrl | URL building and parsing |

Recommended IDE Setup

• VS Code + Volar (and disable Vetur) + TypeScript Vue Plugin (Volar).

PhpStorm (macOS)

If you use PhpStorm on your MacBook, this setup works well for this package:

• JavaScript/TypeScript language service: enabled (default).
• TypeScript version: set to the project's version from node_modules/typescript.
• Vue support: ensure the Vue plugin is enabled.
• Code style/imports: enable optimize imports on save (optional but helpful).

Useful PhpStorm actions for migration from basic-composables to @scoutkirkolson/basic-composables:

• Use Edit → Find → Replace in Files.
• Enable Regex and search with: from\s+['"]basic-composables['"]
• Replace with: from '@scoutkirkolson/basic-composables'
• Scope to your app source folder (for example src).

Development

To develop this project locally and use it in other projects, we recommend using yalc.

Using this package in other projects (yalc for dev, npm for production)

Use this library in two modes:

• Development: consume local changes quickly with yalc.
• Production/CI: consume the published npm package version for reproducible installs.

1) Development mode with yalc

In this basic-composables repo:

corepack yarn build:push

In your consuming project:

yalc add @scoutkirkolson/basic-composables
corepack yarn install

When you make new changes in this repo, run corepack yarn build:push again to push updates.

If the consuming app does not pick up the latest changes, use this refresh flow in the consuming project:

yalc update @scoutkirkolson/basic-composables
corepack yarn install

Hard refresh (only if still stale):

macOS/Linux:

yalc remove @scoutkirkolson/basic-composables
rm -rf .yalc/@scoutkirkolson/basic-composables
rm -rf node_modules/@scoutkirkolson/basic-composables
yalc add @scoutkirkolson/basic-composables
corepack yarn install

Windows PowerShell:

yalc remove @scoutkirkolson/basic-composables
Remove-Item -Recurse -Force .yalc/@scoutkirkolson/basic-composables -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force node_modules/@scoutkirkolson/basic-composables -ErrorAction SilentlyContinue
yalc add @scoutkirkolson/basic-composables
corepack yarn install

Tip: in consuming projects, add a helper script:

{
	"scripts": {
		"deps:composables:refresh": "yalc update @scoutkirkolson/basic-composables && corepack yarn install"
	}
}

2) Production mode from npm

In the consuming project's package.json, pin @scoutkirkolson/basic-composables to a released npm version:

{
	"dependencies": {
		"@scoutkirkolson/basic-composables": "^0.0.14"
	}
}

Example:

{
	"dependencies": {
		"@scoutkirkolson/basic-composables": "0.0.14"
	}
}

Then install:

corepack yarn install

3) Suggested package.json scripts in the consuming project

These scripts make switching explicit and repeatable:

{
	"scripts": {
		"deps:composables:dev": "yalc add @scoutkirkolson/basic-composables && corepack yarn install",
		"deps:composables:prod": "yalc remove @scoutkirkolson/basic-composables && corepack yarn add @scoutkirkolson/[email protected]"
	}
}

Notes:

• Prefer explicit versions in production (0.0.14) instead of floating ranges.
• If your app currently has yalc linked, run yalc remove @scoutkirkolson/basic-composables before switching to npm dependency mode.
• You can still use GitHub refs as a fallback, but npm should be the default production source.

4) Release flow (npm for production)

From this repo, create and push a release tag:

git tag vX.Y.Z
git push origin vX.Y.Z

Publish to npm:

npm publish --access public

Then, in each consuming project, update dependency to that npm version and reinstall:

corepack yarn add @scoutkirkolson/[email protected]
corepack yarn install

Quick check in the consuming project:

corepack yarn why @scoutkirkolson/basic-composables

Rollback (if needed):

corepack yarn add @scoutkirkolson/basic-composables@<previous-version>
corepack yarn install
corepack yarn why @scoutkirkolson/basic-composables

Use an actual previous release version (for example 0.0.11) for <previous-version>.

5) Public release/tag checklist

Before releasing:

• Ensure default branch is up to date.
• Run corepack yarn install and corepack yarn build.
• Update version/changelog notes if needed.

Release:

• Create and push tag: git tag vX.Y.Z && git push origin vX.Y.Z.
• Publish: npm publish --access public.
• In consuming apps, update dependency to @scoutkirkolson/[email protected].
• Reinstall and verify: corepack yarn install && corepack yarn why @scoutkirkolson/basic-composables.

Publishing to npm

This project includes helper scripts in package.json:

• corepack yarn publish:check → build + npm pack --dry-run (preflight)
• corepack yarn publish:npm → publish to npm public registry
• corepack yarn publish:npm:verify → check latest published version
• corepack yarn publish:npm:full → run check + publish + verify in one command

Recommended release flow:

# 1) Ensure auth is valid
npm whoami

# 2) Preflight package contents
corepack yarn publish:check

# 3) Publish
corepack yarn publish:npm

# 4) Verify published version
corepack yarn publish:npm:verify

Or run the one-shot command:

corepack yarn publish:npm:full

If npm publish asks for browser auth in WSL, set:

export BROWSER="$HOME/.local/bin/open-browser-wsl"

Build troubleshooting (Yarn)

This repo is pinned to Yarn 4 with Plug'n'Play (PnP).

Why we use Corepack:

• This repo pins the package manager version in package.json (packageManager: [email protected]).
• corepack yarn ... ensures every developer uses that exact Yarn version, even if their global Yarn is older/different.
• This prevents lockfile/version mismatch issues across macOS, Windows, and Linux.
• It makes CI and local installs behave consistently.

macOS onboarding (recommended for all developers)

On each MacBook, run once:

corepack enable
corepack prepare [email protected] --activate

Then, always run project commands via Corepack:

corepack yarn install
corepack yarn build

Quick verification:

corepack yarn -v

This ensures everyone uses the same Yarn version pinned by this repository, even if a different global Yarn is installed.

Node version recommendation (macOS):

• Use an LTS Node version (recommended: Node 20 or 22).
• If you use a version manager, nvm or volta both work well.

Windows onboarding (recommended for all developers)

In PowerShell (run once):

corepack enable
corepack prepare [email protected] --activate

Then run project commands via Corepack:

corepack yarn install
corepack yarn build
corepack yarn -v

If your machine still uses a different global Yarn, always call corepack yarn ... explicitly.

Node version recommendation (Windows):

• Use an LTS Node version (recommended: Node 20 or 22).
• For version management, prefer nvm-windows or volta so team members stay aligned.

If yarn build fails with lockfile/workspace errors, use:

corepack yarn build

If your shell keeps using a different global yarn, use corepack yarn explicitly.

Check the pinned Yarn version with:

corepack yarn -v

License

MIT