|
1 | | -# AdonisJS package starter kit |
| 1 | +<div align="center"> |
| 2 | + <h1> AdonisJS Transmit</h1> |
| 3 | + <p>A native Server-Sent-Event (SSE) module for AdonisJS.</p> |
| 4 | +</div> |
2 | 5 |
|
3 | | -> A boilerplate for creating AdonisJS packages |
| 6 | +<br /> |
4 | 7 |
|
5 | | -This repo contains the default folder structure, development, and peer dependencies to create a package for AdonisJS v6. |
| 8 | +<div align="center"> |
6 | 9 |
|
7 | | -You can create a package from scratch with your folder structure and workflow. However, using a default starter kit can speed up the process, as you have fewer decisions to make. |
| 10 | +[![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url] [![synk-image]][synk-url] |
8 | 11 |
|
9 | | -## Folder structure |
| 12 | +[gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/adonisjs/transmit/test?style=for-the-badge |
| 13 | +[gh-workflow-url]: https://github.com/adonisjs/transmit/actions/workflows/test.yml "Github action" |
10 | 14 |
|
11 | | -The starter kit mimics the folder structure of the official packages. Feel free to rename files and folders as per your requirements. |
| 15 | +[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript |
| 16 | +[typescript-url]: "typescript" |
12 | 17 |
|
13 | | -``` |
14 | | -├── providers |
15 | | -├── src |
16 | | -├── stubs |
17 | | -├── index.ts |
18 | | -├── LICENSE.md |
19 | | -├── package.json |
20 | | -├── README.md |
21 | | -└── tsconfig.json |
22 | | -``` |
| 18 | +[npm-image]: https://img.shields.io/npm/v/@adonisjs/transmit.svg?style=for-the-badge&logo=npm |
| 19 | +[npm-url]: https://npmjs.org/package/@adonisjs/transmit 'npm' |
23 | 20 |
|
24 | | -- The `providers` directory is used to store service providers. |
25 | | -- The `src` directory contains the source code of the package. All business logic should be inside this folder. |
26 | | -- The `stubs` directory is used to keep scaffolding stubs. You might copy some stubs to the user application once they configure the package. |
27 | | -- The `index.ts` file is the main entry point of the package. |
| 21 | +[license-image]: https://img.shields.io/npm/l/@adonisjs/transmit?color=blueviolet&style=for-the-badge |
| 22 | +[license-url]: LICENSE.md 'license' |
28 | 23 |
|
29 | | -### File system naming convention |
30 | | - |
31 | | -We use `snake_case` naming conventions for the file system. The rule is enforced using ESLint. However, feel free to disable the rule and use your preferred naming conventions. |
32 | | - |
33 | | -## Peer dependencies |
34 | | - |
35 | | -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. |
36 | | - |
37 | | -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`. |
38 | | - |
39 | | -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. |
40 | | - |
41 | | -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). |
42 | | - |
43 | | -## Published files |
44 | | - |
45 | | -Instead of publishing all the source code of your repo to npm, you must cherry-pick files and folders to publish only the required files. |
46 | | - |
47 | | -The cherry-picking is done using the `files` property inside the `package.json` file. By default, we publish the following files and folders. |
48 | | - |
49 | | -```json |
50 | | -{ |
51 | | - "files": [ |
52 | | - "src", |
53 | | - "providers", |
54 | | - "index.ts", |
55 | | - "build/src", |
56 | | - "build/providers", |
57 | | - "build/stubs", |
58 | | - "build/index.d.ts", |
59 | | - "build/index.d.ts.map", |
60 | | - "build/index.js" |
61 | | - ] |
62 | | -} |
63 | | -``` |
64 | | - |
65 | | -If you notice, we are publishing both the source code (written in TypeScript) and the compiled output (JavaScript) to npm. |
66 | | - |
67 | | -- The JavaScript runtime requires compiled output. So that is something you will have to publish. |
68 | | -- Publishing source code is optional. However, if you generate [declaration maps](https://www.typescriptlang.org/tsconfig#declarationMap), then the TypeScript language server (used by code editors like VSCode) will be able to jump to the actual source code when you perform `CTRL + CLICK`. |
69 | | - |
70 | | -If you create additional folders or files, mention them inside the `files` array. |
71 | | - |
72 | | -## Exports |
73 | | - |
74 | | -[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. |
75 | | - |
76 | | -```json |
77 | | -{ |
78 | | - "exports": { |
79 | | - ".": "./build/index.js", |
80 | | - "./types": "./build/src/types.js" |
81 | | - } |
82 | | -} |
83 | | -``` |
84 | | - |
85 | | -- The dot `.` export is the main export. |
86 | | -- The `./types` exports all the types defined inside the `./build/src/types.js` file (the compiled output). |
87 | | - |
88 | | -Feel free to change the exports as per your requirements. |
89 | | - |
90 | | -## Testing |
91 | | - |
92 | | -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. |
93 | | - |
94 | | -- `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). |
95 | | -- `npm run quick:test`: Runs only the tests without linting or coverage reporting. |
96 | | - |
97 | | -The starter kit also comes with a Github workflow file to run tests using Github Actions. The tests are executed against `Node.js 18.x` and `Node.js 19.x` versions on both Linux and Windows. Feel free to edit the workflow file in the `.github/workflows` directory. |
98 | | - |
99 | | -## TypeScript workflow |
100 | | - |
101 | | -- The starter kit uses [tsc](https://www.typescriptlang.org/docs/handbook/compiler-options.html) for compiling the TypeScript to JavaScript at the time of publishing the package. |
102 | | -- [TS-Node](https://typestrong.org/ts-node/) and [SWC](https://swc.rs/) are used to run tests without compiling the source code. |
103 | | -- The `tsconfig.json` file is extended from [`@adonisjs/tsconfig`](https://github.com/adonisjs/tooling-config/tree/main/packages/typescript-config) and uses `NodeNext` module system. Meaning the packages are written using ES modules. |
104 | | -- You can perform type checking without compiling the source code using `npm run typecheck` script. |
105 | | - |
106 | | -Feel free to explore the `tsconfig.json` file for all the configured options. |
107 | | - |
108 | | -## ESLint and Prettier setup |
109 | | - |
110 | | -The starter kit configures ESLint and Prettier. The configuration for both is 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 config, use custom plugins or remove both tools altogether. |
111 | | - |
112 | | -## Using Stale bot (optional) |
113 | | - |
114 | | -The [Stale bot](https://github.com/apps/stale) is a Github application that automatically marks issues and PRs as stale and closes after a certain duration of inactivity. |
115 | | - |
116 | | -You may optionally configure it at the time of scaffolding the package. |
117 | | - |
118 | | -## Unconfigurable bits |
119 | | - |
120 | | -- **License**: The `LICENSE.md` file and the `license` property inside the `package.json` file are set to `MIT`. You can change them manually. |
121 | | -- **Editorconfig**: The `.editorconfig` file is used to define the formatting rules. |
122 | | -- **No package-lock file**: The `.npmrc` file is created with the rule to diable `package-lock.json` file. Feel free to revert the setting or use a different package manager. |
| 24 | +[synk-image]: https://img.shields.io/snyk/vulnerabilities/github/adonisjs/transmit?label=Synk%20Vulnerabilities&style=for-the-badge |
| 25 | +[synk-url]: https://snyk.io/test/github/adonisjs/transmit?targetFile=package.json "synk" |
0 commit comments