|
6 | 6 | [](https://github.com/d3p1/lib-ts-react-template/actions/workflows/release.yml) |
7 | 7 | [](https://github.com/semantic-release/semantic-release) |
8 | 8 |
|
9 | | -</div> |
10 | | - |
11 | | -> [!NOTE] |
12 | | -> Things to mention: `devcontainer`, `.github`, `husky`, `.run`, `commitlint`, `prettier`, package.json settings, vite config, externalize dependencies, explain why react and react-dom are added as dev dependencies, explain how to configure the IDE (Prettier and Startup services), explain local page and demo page and how to configure GitHub pages. Mentions configure token actions |
13 | | -
|
14 | | -> [!NOTE] |
15 | | -> Add examples of libraries created using this template. Explain folder structure for lib development. Mention that to create a granular token only for the specific package, it is required to publish manually for the first time `npm publish`. Also, mention that the token should by pass 2FA. Mentions `tsconfig.app.json` option to allow jsx in `dev` folder. Explain `vite-plugin-dts` config. Explain how to work locally with your package inside `dev`: `npm init` and `npm install ../` |
| 9 | +</div> |
16 | 10 |
|
17 | 11 | ## Introduction |
18 | 12 |
|
19 | | -An efficient image-to-pixel transformation with motion effects, leveraging WebGL's hardware acceleration through [Three.js](https://threejs.org/): |
| 13 | +A template to build [TypeScript](https://www.typescriptlang.org/) libraries with both [Vanilla JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) and [React](https://react.dev/) entry points. |
| 14 | + |
| 15 | +The goal of this template is to simplify the process of creating, maintaining, and publishing libraries. It provides a ready-to-use setup with sensible defaults, including an [automated release workflow triggered on every push to the repository](./.github/workflows/release.yml). |
20 | 16 |
|
21 | | -<div align="center"> |
| 17 | +## Usage |
22 | 18 |
|
23 | | - |
| 19 | +Using this library is straightforward: |
24 | 20 |
|
25 | | -</div> |
| 21 | +1. Click [`Use this template`](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) button to create a fresh repository that uses this template. |
26 | 22 |
|
27 | | -> [!TIP] |
28 | | -> The approach of this implementation bypasses the performance limitations of the 2D canvas API, enabling smooth and dynamic visual effects directly on the GPU. |
| 23 | +2. Update the [`package.json`](./package.json) file so it reflects your library information and needs: |
| 24 | + - `name`: Set your library name. |
| 25 | + - `version`: Start a fresh library with version `0.0.0`. |
| 26 | + - `description`: Add a useful description. |
| 27 | + - `repository`: Define repository information. |
| 28 | + - `author`: Add author information. |
| 29 | + - `bugs`: Set page where the community can report issues. |
| 30 | + - `homepage`: Define a proper homepage for your library. For instance, a link to its [`README.md`](./README.md) file. |
| 31 | + - `keywords`: Add proper keywords. |
29 | 32 |
|
30 | | -> [!TIP] |
31 | | -> If you would like to implement a similar effect on a 3D model, you can use the related library [`d3p1/thr2pxl`](https://github.com/d3p1/thr2pxl), which uses [GPGPU](https://en.wikipedia.org/wiki/General-purpose_computing_on_graphics_processing_units) to achieve it with high performance. |
| 33 | +3. Install project dependencies with `npm install` and run the development server with `npm run dev`. |
32 | 34 |
|
33 | | -> [!NOTE] |
34 | | -> This library was inspired by these excellent tutorials: |
35 | | -> - [Three.js Journey - Particle Cursor Animation Shader](https://threejs-journey.com/lessons/particles-cursor-animation-shader). |
36 | | -> - [Learn Creative Coding: Image Effects](https://www.youtube.com/watch?v=UeZ1pTg_nMo). |
37 | | -> - [Image into Interactive Particles - HTML Canvas Animation Tutorial | Advanced Pure Vanilla JavaScript](https://www.youtube.com/watch?v=afdHgwn1XCY). |
38 | | -
|
39 | | - |
40 | | -## Installation |
41 | | - |
42 | | -You can install this library using a package manager like `npm`: |
43 | | - |
44 | | -```javascript |
45 | | -npm install @d3p1/lib-ts-react-template |
46 | | -``` |
47 | | - |
48 | | -Or you can use a CDN like [jsDelivr](https://www.jsdelivr.com/) and this [importmap](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap) in the `<head>` of your `html` file: |
49 | | - |
50 | | -```html |
51 | | -<head> |
52 | | - ... |
53 | | - <script type="importmap"> |
54 | | - { |
55 | | - "imports": { |
56 | | - "@d3p1/lib-ts-react-template": "https://cdn.jsdelivr.net/npm/@d3p1/lib-ts-react-template@<version>/dist/lib-ts-react-template.min.js", |
57 | | - "three": "https://cdn.jsdelivr.net/npm/three@<version>/build/three.module.min.js", |
58 | | - "tweakpane": "https://cdn.jsdelivr.net/npm/tweakpane@<version>/dist/tweakpane.min.js" |
59 | | - } |
60 | | - } |
61 | | - </script> |
62 | | - ... |
63 | | -</head> |
64 | | -``` |
| 35 | +4. Start your library development. This template comes with sample code inside the [`src` folder](./src). The only important thing to notice is that every feature your library wants to export should be defined inside [`src/core/index.ts`](./src/core/index.ts) and [`src/react/index.ts`](./src/react/index.ts). This is because [they are defined as the entry points of your library](./vite.config.ts). |
65 | 36 |
|
66 | | -> [!NOTE] |
67 | | -> Remember to replace the `<version>` with the actual version of `lib-ts-react-template` and its peer dependencies ([`three`](https://github.com/mrdoob/three.js) and [`tweakpane`](https://github.com/cocopon/tweakpane)). To do that, you can check the [`package.json`](https://github.com/d3p1/lib-ts-react-template/blob/main/package.json) of the last release and get required versions from there. |
| 37 | +5. Install your library in the development site that comes with this template to do a quick validation. Go to [`dev folder`](./dev), remove the `dependencies` from the [`package.json`](./dev/package.json), and execute `npm install ../`. This will install the library so you can consume it. Update the [sample code](./dev/index.html) that comes with this site and visit `http://localhost:5173/dev/` to check the implementation. |
68 | 38 |
|
69 | | -## Usage |
| 39 | +6. Once your library development is completed, you can start the implementation of a demo site. This template comes with a [Next.js](https://nextjs.org/) sample site inside the [`www folder`](./www). There is a [GitHub Action that deploys it on every push](./.github/workflows/deploy-demo.yml). To begin with, update the `basePath` setting inside the [`next.config.ts`](./www/next.config.ts). It should match your repository slug (e.g. `/my-repo-name/`). Then, you can update the [sample code](./www/app) and visit `http://localhost:3000/my-repo-name` to check the implementation. Finally, remember to [enable GitHub Pages with GitHub Actions for your repository](http://localhost:3000/lib-ts-react-template). |
70 | 40 |
|
71 | | -Using this library is straightforward: |
| 41 | +7. Finally, update the [`README.md`](./README.md) so it explains what your library does and how to use it. Remember to update the `release` badge that appears at the top of this [`README.md`](./README.md) if you keep them. It is pointing to this repository. |
72 | 42 |
|
73 | | -1. Go to our [builder page](https://d3p1.github.io/lib-ts-react-template/) and make the desired customizations in the tweak panel to achieve the desired effect. |
74 | | - |
75 | | -2. Use the `Copy` button to obtain the configuration that produces the desired effect. |
76 | | - |
77 | | -3. Instantiate the library with the configuration copied in the previous step, for example: |
78 | | - |
79 | | -```javascript |
80 | | -import Img2Pxl from '@d3p1/lib-ts-react-template' |
81 | | - |
82 | | -new Img2Pxl({ |
83 | | - images: { |
84 | | - 0: { |
85 | | - src: <image-src>, |
86 | | - width: <image-width>, |
87 | | - height: <image-height>, |
88 | | - resolution: { |
89 | | - width: <image-resolution-width>, |
90 | | - height: <image-resolution-height> |
91 | | - }, |
92 | | - pixel: { |
93 | | - size: 2, |
94 | | - alphaTest: 0.9, |
95 | | - motion: { |
96 | | - displacement: { |
97 | | - frequency: 1, |
98 | | - amplitude: 40, |
99 | | - }, |
100 | | - }, |
101 | | - }, |
102 | | - motion: { |
103 | | - noise: { |
104 | | - frequency: 0.025, |
105 | | - amplitude: 40, |
106 | | - }, |
107 | | - }, |
108 | | - }, |
109 | | - }, |
110 | | - pointer: { |
111 | | - size: 0.1, |
112 | | - trailing: { |
113 | | - factor: 0.01 |
114 | | - } |
115 | | - } |
116 | | -}) |
117 | | -``` |
| 43 | +> [!NOTE] |
| 44 | +> To gain a deeper understanding of how to use this library and how it works under the hood, visit the [wiki page](https://github.com/d3p1/lib-ts-react-template/wiki). |
118 | 45 |
|
119 | 46 | > [!NOTE] |
120 | | -> To gain a deeper understanding of how to use this library and how it works under the hood, visit the [wiki page](https://github.com/d3p1/lib-ts-react-template/wiki) _(in progress)_. |
| 47 | +> There is a [ticket](https://github.com/d3p1/lib-ts-react-template/issues/4) to add testing tools to improve the library's validation workflow. |
121 | 48 |
|
122 | 49 | ## Changelog |
123 | 50 |
|
|
0 commit comments