Skip to content

Commit

Permalink
fix: include configure in files
Browse files Browse the repository at this point in the history
  • Loading branch information
tomgobich committed Jun 1, 2024
1 parent 7b66490 commit 4f7ad28
Show file tree
Hide file tree
Showing 2 changed files with 42 additions and 103 deletions.
141 changes: 39 additions & 102 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,115 +1,52 @@
# AdonisJS package starter kit
# @adocasts.com/actions

> A boilerplate for creating AdonisJS packages
Easily strub new action classes inside your AdonisJS 6 project

This repo provides you with a starting point for creating AdonisJS packages. Of course, you can create a package from scratch with your folder structure and workflow. However, using this starter kit can speed up the process, as you have fewer decisions to make.

## Setup

- Clone the repo on your computer, or use `giget` to download this repo without the Git history.
```sh
npx giget@latest gh:adonisjs/pkg-starter-kit
## Install With Ace
```shell
node ace add @adocasts.com/actions
```
- Install dependencies.
- Update the `package.json` file and define the `name`, `description`, `keywords`, and `author` properties.
- The repo is configured with an MIT license. Feel free to change that if you are not publishing under the MIT license.

## Folder structure

The starter kit mimics the folder structure of the official packages. Feel free to rename files and folders as per your requirements.
- Installs `@adocasts.com/actions`.
- Automatically configures the `make:action` command via your `adonisrc.ts` file.

## Manual Install & Configure
First, install
```shell
npm i @adocasts.com/actions@latest
```
├── providers
├── src
├── bin
├── stubs
├── configure.ts
├── index.ts
├── LICENSE.md
├── package.json
├── README.md
├── tsconfig.json
├── tsnode.esm.js
Then, configure
```shell
node ace configure @adocasts.com/actions
```

- The `configure.ts` file exports the `configure` hook to configure the package using the `node ace configure` command.
- The `index.ts` file is the main entry point of the package.
- The `tsnode.esm.js` file runs TypeScript code using TS-Node + SWC. Please read the code comment in this file to learn more.
- The `bin` directory contains the entry point file to run Japa tests.
- Learn more about [the `providers` directory](./providers/README.md).
- Learn more about [the `src` directory](./src/README.md).
- Learn more about [the `stubs` directory](./stubs/README.md).

### File system naming convention

We use `snake_case` naming conventions for the file system. The rule is enforced using ESLint. However, turn off the rule and use your preferred naming conventions.

## Peer dependencies

The starter kit has a peer dependency on `@adonisjs/core@6`. Since you are creating a package for AdonisJS, you must make it against a specific version of the framework core.
## Using
Once `@adocasts.com/actions` is installed & configured in your application,
you'll have access to `node ace make:actions [name]`.

If your package needs Lucid to be functional, you may install `@adonisjs/lucid` as a development dependency and add it to the list of `peerDependencies`.

As a rule of thumb, packages installed in the user application should be part of the `peerDependencies` of your package and not the main dependency.

For example, if you install `@adonisjs/core` as a main dependency, then essentially, you are importing a separate copy of `@adonisjs/core` and not sharing the one from the user application. Here is a great article explaining [peer dependencies](https://blog.bitsrc.io/understanding-peer-dependencies-in-javascript-dbdb4ab5a7be).

## Published files

Instead of publishing your repo's source code to npm, you must cherry-pick files and folders to publish only the required files.

The cherry-picking uses the `files` property inside the `package.json` file. By default, we publish the following files and folders.

```json
{
"files": ["build/src", "build/providers", "build/stubs", "build/index.d.ts", "build/index.js"]
}
For example, to create a `RegisterFromForm` action, you can do:
```shell
node ace make:action RegisterFromForm
```

If you create additional folders or files, mention them inside the `files` array.

## Exports

[Node.js Subpath exports](https://nodejs.org/api/packages.html#subpath-exports) allows you to define the exports of your package regardless of the folder structure. This starter kit defines the following exports.

```json
{
"exports": {
".": "./build/index.js",
"./types": "./build/src/types.js"
}
}
Which creates an action class at:
```shell
app/actions/register_from_form.ts
```

- The dot `.` export is the main export.
- The `./types` exports all the types defined inside the `./build/src/types.js` file (the compiled output).

Feel free to change the exports as per your requirements.

## Testing

We configure the [Japa test runner](https://japa.dev/) with this starter kit. Japa is used in AdonisJS applications as well. Just run one of the following commands to execute tests.

- `npm run test`: This command will first lint the code using ESlint and then run tests and report the test coverage using [c8](https://github.com/bcoe/c8).
- `npm run quick:test`: Runs only the tests without linting or coverage reporting.

The starter kit also has a Github workflow file to run tests using Github Actions. The tests are executed against `Node.js 20.x` and `Node.js 21.x` versions on both Linux and Windows. Feel free to edit the workflow file in the `.github/workflows` directory.

## TypeScript workflow

- The starter kit uses [tsc](https://www.typescriptlang.org/docs/handbook/compiler-options.html) for compiling the TypeScript to JavaScript when publishing the package.
- [TS-Node](https://typestrong.org/ts-node/) and [SWC](https://swc.rs/) are used to run tests without compiling the source code.
- The `tsconfig.json` file is extended from [`@adonisjs/tsconfig`](https://github.com/adonisjs/tooling-config/tree/main/packages/typescript-config) and uses the `NodeNext` module system. Meaning the packages are written using ES modules.
- You can perform type checking without compiling the source code using the `npm run type check` script.

Feel free to explore the `tsconfig.json` file for all the configured options.

## ESLint and Prettier setup

The starter kit configures ESLint and Prettier. Both configurations are stored within the `package.json` file and use our [shared config](https://github.com/adonisjs/tooling-config/tree/main/packages). Feel free to change the configuration, use custom plugins, or remove both tools altogether.

## Using Stale bot
### Features
Apps have lots of actions, so it's a great idea to group them into feature/resource folders.
This can be easily done via the `--feature` flag.
```shell
node ace make:action register_from_form --feature=auth
```
This will then create our action class at:
```shell
app/actions/auth/register_from_form.ts
```
Also, note in both the above examples, the file name was normalized.

The [Stale bot](https://github.com/apps/stale) is a Github application that automatically marks issues and PRs as stale and closes after a specific duration of inactivity.
### HTTP Actions
If your action is going to handle an HTTP Request, you can optionally include an injection of the `HttpContext` directly within your action class via the `--http` flag.
```shell
node ace make:action register_from_form --http --feature=auth
```

Feel free to delete the `.github/stale.yml` and `.github/lock.yml` files if you decide not to use the Stale bot.
4 changes: 3 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,14 +1,16 @@
{
"name": "@adocasts.com/actions",
"description": "Adds a make:action Ace CLI command to easily create new action handler classes in your AdonisJS 6 application",
"version": "0.0.0",
"version": "0.0.2",
"engines": {
"node": ">=20.6.0"
},
"type": "module",
"files": [
"build/commands",
"build/stubs",
"build/configure.d.ts",
"build/configure.js",
"build/index.d.ts",
"build/index.js"
],
Expand Down

0 comments on commit 4f7ad28

Please sign in to comment.