npm package: @scoutkirkolson/basic-composables
Description: Basic composables for Vue 3 projects
Author: Scout Kirk Olson
Latest version: 0.0.15

# basic-composables

A collection of basic composables for Vue 3 projects.

## Table of Contents

- [Breaking Change (Package Rename)](#breaking-change-package-rename)
- [Installation](#installation)
- [Usage](#usage)
- [Available Composables](#available-composables)
- [Recommended IDE Setup](#recommended-ide-setup)
- [Development](#development)
- [Publishing to npm](#publishing-to-npm)
- [Build troubleshooting (Yarn)](#build-troubleshooting-yarn)
- [License](#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:

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

And replace imports:

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

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

Temporary compatibility option for production installs:

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

## Installation

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

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

## Usage

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

### Migration from `basic-composables` imports

If existing projects still use:

```js
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`:

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

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):

```bash
# 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):

```powershell
# 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](https://momentjs.com/)) |
| `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](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) + [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin).

### 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](https://github.com/whitecolor/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:

```bash
corepack yarn build:push
```

In your consuming project:

```bash
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:

```bash
yalc update @scoutkirkolson/basic-composables
corepack yarn install
```

Hard refresh (only if still stale):

macOS/Linux:

```bash
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:

```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:

```json
{
	"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:

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

Example:

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

Then install:

```bash
corepack yarn install
```

#### 3) Suggested package.json scripts in the consuming project

These scripts make switching explicit and repeatable:

```json
{
	"scripts": {
		"deps:composables:dev": "yalc add @scoutkirkolson/basic-composables && corepack yarn install",
		"deps:composables:prod": "yalc remove @scoutkirkolson/basic-composables && corepack yarn add @scoutkirkolson/basic-composables@0.0.14"
	}
}
```

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:

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

Publish to npm:

```bash
npm publish --access public
```

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

```bash
corepack yarn add @scoutkirkolson/basic-composables@X.Y.Z
corepack yarn install
```

Quick check in the consuming project:

```bash
corepack yarn why @scoutkirkolson/basic-composables
```

Rollback (if needed):

```bash
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/basic-composables@X.Y.Z`.
- 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:

```bash
# 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:

```bash
corepack yarn publish:npm:full
```

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

```bash
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: yarn@4.12.0`).
- `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:

```bash
corepack enable
corepack prepare yarn@4.12.0 --activate
```

Then, always run project commands via Corepack:

```bash
corepack yarn install
corepack yarn build
```

Quick verification:

```bash
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):

```powershell
corepack enable
corepack prepare yarn@4.12.0 --activate
```

Then run project commands via Corepack:

```powershell
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:

```bash
corepack yarn build
```

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

Check the pinned Yarn version with:

```bash
corepack yarn -v
```

## License

[MIT](./LICENSE)