Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New documentation #120

Merged
merged 23 commits into from
Oct 9, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
101a225
fix(svg): make params optional and sync param names
secundant Aug 4, 2023
74f693c
docs(svg): add basic documentation about API
secundant Aug 4, 2023
93154c8
fix(svg): simplify generated metadata types
secundant Aug 6, 2023
d0d66d3
docs(svg): add `@neodx/svg` documentation, update examples
secundant Aug 6, 2023
8480440
docs(svg): rework package README with links to external docs
secundant Aug 8, 2023
f3d6728
docs(svg): update `svg-vite` example
secundant Aug 8, 2023
632acb4
docs(figma): link in root README, add some APIs notes
secundant Aug 8, 2023
f1d3cca
feat(log): rework `createLoggerFactory` levels types
secundant Aug 18, 2023
1cd6956
docs(log): write about core APIs
secundant Aug 18, 2023
b561364
docs(log): add frameworks, motivation and a guide for creating custom…
secundant Aug 18, 2023
de418c5
docs: add favicons, choose theme colors
secundant Aug 20, 2023
0b377c4
chore: upgrade dev dependencies
secundant Sep 12, 2023
d48ceeb
docs: update theme
secundant Sep 19, 2023
31247c0
docs(log): rework documentation (~90% complete)
secundant Sep 19, 2023
32ae4c0
chore: update dependencies
secundant Oct 8, 2023
26d3339
docs(log): finish base `@neodx/log` documentation
secundant Oct 8, 2023
ce0e733
fix(svg): update tests
secundant Oct 8, 2023
f30d6b1
chore(log): internals patches
secundant Oct 8, 2023
004f4b7
feat(std): add first `typeof ...` shortcuts
secundant Oct 8, 2023
4f5ba33
docs: add documentation reference, extend dev guide
secundant Oct 8, 2023
8179bf1
changeset: describe packages updates
secundant Oct 8, 2023
c2c3212
fix: fix typo issue in example app
secundant Oct 8, 2023
2614a03
changeset(log): add note about new docs
secundant Oct 8, 2023
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/eight-bobcats-refuse.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@neodx/figma': minor
---

New documentation
5 changes: 5 additions & 0 deletions .changeset/funny-knives-kiss.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@neodx/log': minor
---

Rework `createLoggerFactory` levels types
5 changes: 5 additions & 0 deletions .changeset/itchy-snails-agree.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@neodx/svg': patch
---

Make the argument for builder params optional
5 changes: 5 additions & 0 deletions .changeset/nasty-horses-heal.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@neodx/svg': patch
---

Simplify generated metadata types
5 changes: 5 additions & 0 deletions .changeset/new-geckos-wink.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@neodx/svg': minor
---

New documentation
5 changes: 5 additions & 0 deletions .changeset/red-trees-poke.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@neodx/std': minor
---

Add first `typeof ...` shortcuts
5 changes: 5 additions & 0 deletions .changeset/wet-papayas-think.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@neodx/log': patch
---

New documentation
File renamed without changes.
2 changes: 1 addition & 1 deletion .yarnrc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ changesetIgnorePatterns:
- '**/*.test.{js,ts,tsx}'
- '**/*.spec.{js,ts,tsx}'

defaultSemverRangePrefix: '^'
defaultSemverRangePrefix: ''

enableGlobalCache: false

Expand Down
218 changes: 71 additions & 147 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,51 +7,77 @@

This project is designed to tackle common web development challenges with ease.

Check out our [documentation](https://neodx.pages.dev) to learn more!

> **Warning**
> Most of the packages are still under development, so API may change.
> I'll try to keep it stable, but updates still can bring breaking changes.

Packages overview:

- [@neodx/figma](#neodxfigma) | [docs](https://neodx.pages.dev/figma) | [source](./libs/figma)
- [@neodx/svg](#neodxsvg) | [docs](https://neodx.pages.dev/svg) | [source](./libs/svg)
- [@neodx/log](#neodxlog) | [docs](https://neodx.pages.dev/log) | [source](./libs/log)

### [@neodx/figma](./libs/figma)

Figma is a great tool for design collaboration, but we don't have a solid way to use it in our development workflow.

#### But we have a problem!

Probably, you've already tried to write your own integration or use some existing solutions and faced the following problems as me:

- Multiple different not maintained packages with different APIs
- Bad documentation/usage examples or even no documentation at all
- Terrible flexibility and solution design, you just can't use it in your project because of the different document structure or workflow
- No type safety, autocomplete, etc.
- 🤯 Multiple different not maintained packages with different APIs
- 🫠 Bad documentation/usage examples or even no documentation at all
- 💀 Terrible flexibility and solution design, you just can't use it in your project because of the different document structure or workflow
- 🙅‍♀️ No type safety, autocomplete, etc.

In other words, there is no really well-designed complex solution for Figma integration.

#### Let's solve it!

So, `@neodx/figma` is an attempt to create it. Currently, we have the following features:

- **Flexible Export CLI**: You can use it to export icons or other elements. It's a simple wrapper around our Node.JS API.
- **Typed Figma API**: All Figma API methods are typed and have autocomplete support.
- **Built-in document graph API**: Figma API is too low-level for writing any stable solution. We provide an API that allows you work with the document as a simple high-level graph of nodes.

[Visit `@neodx/figma` documentation](https://neodx.pages.dev/svg) to learn more!

See our examples for more details:

- [SVG sprite generation on steroids with Figma export](./examples/svg-magic-with-figma-export) - Integrated showcase of the `@neodx/svg` and `@neodx/figma` packages with real application usage!
- [Export icons from the Community Weather Icons Kit](./examples/figma-export-file-assets) - A simple step-by-step example of how to use the `@neodx/figma` to export icons.

We have a some ideas for future development, so stay tuned and feel free to request your own! 🚀
Also, we have some ideas for future development, so stay tuned and feel free to request your own! 🚀

### [@neodx/svg](./libs/svg)

Supercharge your icons ⚡️

Are you converting every SVG icon to a React component with SVGR or something similar? It's so ease to use!

But wait; did you know that SVG sprites are a native approach for icons? It's even easier to use!

```typescript jsx
import { Icon } from '@/shared/ui';
import { Icon, type AnyIconName } from '@/shared/ui/icon';

export interface MyComponentProps {
icon: AnyIconName;
}

export const MyComponent = () => (
export const MyComponent = ({ icon }: MyComponentProps) => (
<>
<Icon name="check" />
<Icon name="close" className="text-red-500" />
{/* Use as is */}
<Icon name="common/check" />
{/* Change color */}
<Icon name="common/close" className="text-red-500" />
{/* Change size */}
<Icon name="text/bold" className="text-lg" />
{/* Add any other styles */}
<Icon name="actions/delete" className="p-2 rounded-md bg-stone-300" />
{/* Use simple type-safe names instead of weird components */}
<Icon name={icon} />
</>
);
```
Expand All @@ -61,143 +87,15 @@ No runtime overhead, one component for all icons, native browser support, static
Sounds good? Of course! Native sprites are unfairly deprived technique.
Probably, you already know about it, but didn't use it because of the lack of tooling.

Here we go! Type safety, autocomplete, runtime access to icon metadata all wrapped in simple plugins for all popular bundlers (thx [unplugin](https://github.com/unjs/unplugin)) and CLI, for example:

<details>
<summary>Vite plugin</summary>

```typescript
import { defineConfig } from 'vite';
import svg from '@neodx/svg/vite';

export default defineConfig({
plugins: [
svg({
root: 'assets',
output: 'public',
metadata: 'src/shared/ui/icon/sprite.gen.ts'
})
]
});
```

</details>
Here we go! Type safety, autocomplete, runtime access to icon metadata all wrapped in simple plugins for all popular bundlers.

<details>
<summary>Webpack plugin</summary>

```typescript
import svg from '@neodx/svg/webpack';

export default {
plugins: [
svg({
root: 'assets',
output: 'public',
metadata: 'src/shared/ui/icon/sprite.gen.ts'
})
]
};
```

</details>

<details>
<summary>Rollup plugin</summary>

```typescript
import svg from '@neodx/svg/rollup';

export default {
plugins: [
svg({
root: 'assets',
output: 'public',
metadata: 'src/shared/ui/icon/sprite.gen.ts'
})
]
};
```

</details>

<details>
<summary>ESBuild plugin</summary>

```typescript
import svg from '@neodx/svg/esbuild';

export default {
plugins: [
svg({
root: 'assets',
output: 'public',
metadata: 'src/shared/ui/icon/sprite.gen.ts'
})
]
};
```
[Visit `@neodx/svg` documentation](https://neodx.pages.dev/svg) to learn more!

</details>

<details>
<summary>CLI</summary>

```shell
npx @neodx/svg --group --root assets --output public --definition src/shared/ui/icon/sprite.gen.ts
# --root - root folder with SVGs
# --group - group icons by folders (assets/common/add.svg -> common/add, assets/other/cut.svg -> other/cut)
# --output (-o) - output folder for sprites
# --definition (-d) - output file for sprite definitions
```

</details>

<details>
<summary>Node.JS API (programmatic usage, low-level)</summary>

```typescript
import { buildSprites } from '@neodx/svg';
import { createVfs } from '@neodx/vfs';

await buildSprites({
vfs: createVfs(process.cwd()),
root: 'assets',
input: '**/*.svg',
output: 'public',
metadata: 'src/shared/ui/icon/sprite.gen.ts'
});
```

</details>

For the details and real usage see our examples:
Also, you can check out our examples:

- [React, Vite, TailwindCSS, and multicolored icon](./examples/svg-vite) - A step-by-step tutorial showcasing how to integrate sprite icons into your Vite project.
- [React, Vite, icons exported by "@neodx/figma"](./examples/svg-magic-with-figma-export) - Integrated showcase of the seamless automation capabilities of `@neodx/svg` and `@neodx/figma` for your icons!
- [NextJS, webpack and simple flat icons](./examples/svg-next) - An example demonstrating the usage of `@neodx/svg` webpack plugin with NextJS.

In the result, you'll get something like this:

```diff
...
src/
shared/
ui/
icon/
+ sprite.gen.ts // sprite definitions - types, metadata, etc.
public/
+ sprite/
+ common.svg
+ other.svg
assets/
common/
add.svg
close.svg
other/
cut.svg
search.svg
```
- [Next.js, webpack and simple flat icons](./examples/svg-next) - An example demonstrating the usage of `@neodx/svg` webpack plugin with Next.js.

### [@neodx/log](./libs/log)

Expand Down Expand Up @@ -298,26 +196,52 @@ async function doSomethingWithVfs(vfs: Vfs) {
While it may seem unnecessary at first glance, let's explore the core concepts that make `@neodx/vfs` invaluable:

- Single abstraction - just share `Vfs` instance between all parts of your tool
- Inversion of control - you can provide any implementation of `Vfs` interface
- Inversion of control: you can provide any implementation of `Vfs` interface
- Btw, we already have built-in support in the `createVfs` API
- Dry-run mode - you can test your tool without any side effects (only in-memory changes, read-only FS access)
- Virtual mode - you can test your tool without any real file system access, offering in-memory emulation for isolated testing
- Dry-run mode: you can test your tool without any side effects (only in-memory changes, read-only FS access)
- Virtual mode: you can test your tool without any real file system access, offering in-memory emulation for isolated testing
- Attached working directory - you can use clean relative paths in your logic without any additional logic
- Extensible - you can build your own features on top of `Vfs` interface
- Extensible: you can build your own features on top of `Vfs` interface
- Currently, we have built-in support for formatting files, updating JSON files, and package.json dependencies management

In other words, it's designed as single API for all file system operations, so you can focus on your tool logic instead of reinventing the wheel.

## Development and contribution

### Getting started

We're using [Yarn 3 (berry)](https://yarnpkg.com/) as a package manager and [Nx](https://nx.dev/) as a monorepo management tool.

After cloning the repo, to install dependencies, run:

```shell
yarn
```

And, optionally, for building all packages, run:

```shell
yarn nx run-many --all --target=build
```

It isn't necessary, you can start working with the codebase right away, but it will boost initial cache whn you run e2e tests (scenarios in examples/\*).

### Internal scripts

#### Create new library
#### Create a new global example

```shell
yarn neodx lib my-lib-name
yarn neodx example new-example-name
```

#### Create a new library

```shell
yarn neodx lib new-lib-name
```

The source code can be accessed by starting from [tools/scripts/bin.mjs](./tools/scripts/bin.mjs)..

## License

Licensed under the [MIT License](./LICENSE).
Loading