Initial commit

.github/workflows/test.yml

@@ -0,0 +1,99 @@
+name: Test
+
+on:
+  ## This workflow runs on every push to main (including merges)
+  push:
+    branches: [main]
+  ## This workflow also runs for every opened PR or push to PR branch
+  pull_request:
+
+jobs:
+  ## First job that runs is linting. This ensures the syntax is valid in the
+  ## first place. Feel free to reduce to `pnpm lint` if your ruleset is set up
+  ## to where warnings are only stylistic preferences and not vital to ensure
+  ## code validity.
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install pnpm v9
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - name: Install Node.js v22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --ignore-scripts
+      - name: Lint
+        run: pnpm lint:strict
+
+  ## This job runs after lint and runs prettier in check mode.
+  ## Feel free to remove this if you're not strict with codestyle
+  format:
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install pnpm v9
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - name: Install Node.js v22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --ignore-scripts
+      - name: Check Formatting
+        run: pnpm format:check
+
+  ## This job runs after lint and runs TypeScript typechecks
+  types:
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install pnpm v9
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - name: Install Node.js v22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --ignore-scripts
+      - name: Typecheck
+        run: pnpm typecheck
+
+  test:
+    needs: types
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # it is recommended to test at least previous LTS, LTS and Latest node
+        node-version: [20.x, 22.x, 23.x]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install pnpm v9
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: pnpm
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --ignore-scripts
+      - name: Run Tests
+        run: pnpm test

.gitignore

@@ -0,0 +1,11 @@
+logs
+*.log
+.pnpm-debug.log*
+node_modules/
+*.tsbuildinfo
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+dist/

.npmrc

@@ -0,0 +1 @@
+ignore-dep-scripts=true

.prettierignore

@@ -0,0 +1,2 @@
+dist
+pnpm-lock.yaml

.prettierrc.json

@@ -0,0 +1,10 @@
+{
+  "printWidth": 80,
+  "tabWidth": 2,
+  "semi": true,
+  "singleQuote": false,
+  "jsxSingleQuote": false,
+  "trailingComma": "none",
+  "bracketSameLine": true,
+  "arrowParens": "avoid"
+}

.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "yoavbls.pretty-ts-errors"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+  "eslint.experimental.useFlatConfig": true,
+  "editor.formatOnSave": true,
+  "[javascript][typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true
+  },
+  "[json][jsonc][yaml]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true
+  }
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Foxkit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+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 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.

README.md

@@ -0,0 +1,90 @@
+# Foxkit Library Template
+
+This repository is a template for dual-published npm packages with [esbuild] and full [TypeScript] support.
+
+## Getting Started
+
+First make sure you have a recent version of Node.js (see [Releases](https://nodejs.dev/en/about/releases/)) and [pnpm] installed.
+
+Create your repository using the button above. Once cloned move into the project directory and run `pnpm install`. You can now start development in "src/index.ts" or read the rest of this documentation to get more familiar with the build/publishing process and provided pre-configured tools.
+
+Remember to replace README.md and adjust (at least the name) in the LICENSE file before publishing!
+
+## Configuring Builds
+
+The build process contains three steps: A build script using [esbuild], d.ts files through `tsc` ([TypeScript]).
+
+The build script is a simple js file which can be freely adjusted. The provided configurations are for dual-publishing as native ES Modules with `.cjs` as fallback for older systems, while [TypeScript] takes care of providing types in d.ts files.
+
+### Configuring package.json publishConfig
+
+The build script uses the `"publishConfig"` to override and add keys in your production package.json file. This is achieved with a simple `Object.assign` call, so you can nest another `"publishConfig"` object inside to configure `npm publish` from there (note that this is slightly different from how pnpm handles this!). See the [pnpm docs](https://pnpm.io/package_json#publishconfig) for detailed information on available parameters that can be overriden.
+
+When not using the `"exports"` key, in general `"main"` should be your cjs build, `"module"` your js (ESM) build and `"types"` should be added appropriately. Note that when using the `"exports"` key you should add `"types"` as the first key on every export to make sure [TypeScript] can find them. If you are exporting a file in a subdirectory of `./src` you may want to use the `"typesVersion"` key as a workaround for linking to the d.ts file as a workaround.
+
+## Tools
+
+### ESLint
+
+[ESLint] is the go-to linter for JavaScript and TypeScript and is configured using [eslint-config-foxkit] and [eslint-config-prettier]. The config file uses the newer [Flat Config] style and is pre-configured with strict rulesets for JS and TS.
+
+Run the `pnpm lint` or `pnpm lint:strict` scripts or install the editor integration for your code editor, such as the [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) to run ESLint.
+
+### Prettier
+
+[Prettier] is an automatic code-formatter and is configured to auto-format all appropriate file types when creating a commit with git through [simple-git-hooks] and [nano-staged].
+
+If you would like to remove git hooks simply uninstall the packages, remove their settings and the `"prepare"` script from package.json and delete the git hook file:
+
+```sh
+pnpm remove simple-git-hooks nano-staged
+rm .git/hooks/pre-commit
+```
+
+Installing the editor integration for your code editor, such as the [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode), is strongly recommended. You can also manually call prettier for the entire codebase with the `pnpm format` script or check for formatting errors with the `pnpm format:check` script.
+
+### uvu
+
+This repository comes with the test runner [uvu] set up to run from the `"tests"` directory. You can add any testing utilities in `"tests/utils"` (the `utils` directory is ignored by uvu). Test files fully support TypeScript thanks to `esbuild-register`. To run your tests simply run the command `pnpm test`.
+
+## Publishing
+
+- You should commit (or stash) any changes and ran `pnpm lint` and any tests (if you added any) before publishing!
+- Increase the `"version"` key in your package.json appropriately (see [About semantic versioning](https://docs.npmjs.com/about-semantic-versioning)) then push a commit with this version:
+
+```sh
+# replace vX.X.X with your version!
+git add package.json
+git commit -m "vX.X.X"
+```
+
+- Now build your package, move into the dist directory and publish:
+
+```sh
+pnpm build
+cd dist
+npm publish # you can use --dry-run to test that all your files are included properly!
+```
+
+- If this succeeded and your package is now published you can push the versioning commit and create a tag
+
+```sh
+cd .. # exit dist directory
+git push
+git tag "vX.X.X" -m "vX.X.X"
+git push --tags
+```
+
+- Remember to create a Release on Github!
+
+[esbuild]: https://esbuild.github.io/
+[TypeScript]: https://www.typescriptlang.org/
+[pnpm]: https://pnpm.io/
+[ESLint]: https://eslint.org/
+[eslint-config-foxkit]: https://github.com/foxkit-js/eslint-config-foxkit
+[eslint-config-prettier]: https://github.com/prettier/eslint-config-prettier
+[Flat Config]: https://eslint.org/docs/latest/use/configure/configuration-files-new
+[Prettier]: https://prettier.io/
+[simple-git-hooks]: https://github.com/toplenboren/simple-git-hooks
+[nano-staged]: https://github.com/usmanyunusov/nano-staged
+[uvu]: https://github.com/lukeed/uvu