Skip to content

Commit

Permalink
📝 update README.md
Browse files Browse the repository at this point in the history 
Signed-off-by: birjuvachhani <[email protected]>
  • Loading branch information
@BirjuVachhani
BirjuVachhani committed Jul 28, 2020
1 parent 883c3c6 commit d73ad5f
Showing 1 changed file with 57 additions and 63 deletions.
120 changes: 57 additions & 63 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,11 @@

# Spider

A small dart library to generate Assets dart code from assets folder.
It generates dart class with static const variables in it which can
be used to reference the assets safely anywhere in the flutter app.
A small dart library to generate Assets dart code from assets folder. It generates dart class with static const variables in it which can be used to reference the assets safely anywhere in the flutter app.

## Breaking Changes since v1.0.0:

> Instead of declaring `package` name separately for each group, spider now takes `package` key-value pair as a global configuration.
### Example

Expand All @@ -30,15 +32,11 @@ class Assets {
}
```

This method allows no error scope for string typos. Also, it provides
auto-complete in the IDE which comes very handy when you have
large amount of assets.
This method allows no error scope for string typos. Also, it provides auto-complete in the IDE which comes very handy when you have large amount of assets.

## Installation

This is package is an independent library that is not linked to your
project. So there's no need to add it to your flutter project as it
works as a global command line tool for all of your projects.
This is package is an independent library that is not linked to your project. So there's no need to add it to your flutter project as it works as a global command line tool for all of your projects.

```shell
pub global activate spider
Expand All @@ -53,38 +51,48 @@ spider --help
## Usage

#### Create Configuration File
Spider provides a very easy and straight forward way to create
a configuration file.
Execute following command and it will create a configuration file
with default configurations in it.
Spider provides a very easy and straight forward way to create a configuration file. Execute following command and it will create a configuration file with default configurations in it.

```shell
spider create
```

Now you can modify available configurations and Spider will use
those configs when generating dart code.
Now you can modify available configurations and Spider will use those configs when generating dart code.

#### Use JSON config file

Though above command creates `YAML` format for config file, spider
also supports `JSON` format for config file. Use this command to
create `JSON` config file instead of `YAML`.
Though above command creates `YAML` format for config file, spider also supports `JSON` format for config file. Use this command to create `JSON` config file instead of `YAML`.

```shell
spider create --json
```

No matter which config format you use, `JSON` or `YAML`, spider
automatically detects it and uses it for code generation.
No matter which config format you use, `JSON` or `YAML`, spider automatically detects it and uses it for code generation.

Here's the default configuration that will be in the config file:

```yaml
# Generated by Spider

# Generates unit tests to verify that the assets exists in assets directory
generate_tests: true

# Use this to remove vcs noise created by the `generated` comments in dart code
no_comments: true

# Exports all the generated file as the one library
export: true

# This allows you to import all the generated references with 1 single import!
use_part_of: true

# Location where all the generated references will be stored
package: resources

groups:
- path: assets/images
class_name: Images
package: res
types: [ .png, .jpg, .jpeg, .webp, .webm, .bmp ]
```
### Generate Code
Expand All @@ -97,6 +105,8 @@ spider build

### Manual

> Note: This is a table! If it looks like some verbose logs rather than looking like a table, then head over to the [repository](https://github.com/birjuvachhani/spider) to make it look like a table.
| KEY | TYPE | DEFAULT VALUE | SCOPE | DESCRIPTION |
|----------------- |-------------- |---------------- |-------- |------------------------------------------------------------------------------------------------------- |
| `path/paths`* | String | None | GROUP | Where to locate assets? |
Expand All @@ -113,8 +123,7 @@ spider build


### Watch Directory
Spider can also watch given directory for changes in files and rebuild
dart code automatically. Use following command to watch for changes:
Spider can also watch given directory for changes in files and rebuild dart code automatically. Use following command to watch for changes:

```shell
spider build --watch
Expand All @@ -127,11 +136,7 @@ spider build --help

### Smart Watch (Experimental)

The normal `--watch` option watches for any kind of changes that happens
in the directory. However this can be improved my smartly watching the
directory. It includes ignoring events that doesn't affect anything like
file content changes. Also, it only watches allowed file types and
rebuilds upon changes for those files only.
The normal `--watch` option watches for any kind of changes that happens in the directory. However this can be improved my smartly watching the directory. It includes ignoring events that doesn't affect anything like file content changes. Also, it only watches allowed file types and rebuilds upon changes for those files only.

Run following command to watch directories smartly.

Expand All @@ -141,8 +146,7 @@ spider build --smart-watch

### Categorizing by File Extension

By default, Spider allows any file to be referenced in the dart code.
but you can change that behavior. You can specify which files you want to be referenced.
By default, Spider allows any file to be referenced in the dart code. but you can change that behavior. You can specify which files you want to be referenced.

```yaml
path: assets
Expand All @@ -152,8 +156,7 @@ types: [ jpg, png, jpeg, webp, bmp, gif ]
```
### Use Prefix
You can use prefixes for names of the generated dart references.
Prefixes will be attached to the formatted reference names.
You can use prefixes for names of the generated dart references. Prefixes will be attached to the formatted reference names.
```yaml
path: assets
Expand All @@ -172,15 +175,10 @@ class Assets {
```

## Advanced Configuration
Spider provides supports for multiple configurations and classifications.
If you wanna group your assets by module, type or anything, you can do
that using `groups` in spider.
Spider provides supports for multiple configurations and classifications. If you wanna group your assets by module, type or anything, you can do that using `groups` in spider.

### Example
Suppose you have both vector(SVGs) and raster images in your project
and you want to me classified separately so that you can use them with
separate classes. You can use groups here. Keep your vector and raster
images in separate folder and specify them in the config file.
Suppose you have both vector(SVGs) and raster images in your project and you want to me classified separately so that you can use them with separate classes. You can use groups here. Keep your vector and raster images in separate folder and specify them in the config file.

`spider.yaml`
```yaml
Expand All @@ -193,20 +191,13 @@ groups:
package: res
```
Here, first item in the list indicates to group assets of
`assets/images` folder under class named `Images` and the second
one indicates to group assets of `assets/vectors` directory under
class named `Svgs`.
Here, first item in the list indicates to group assets of `assets/images` folder under class named `Images` and the second one indicates to group assets of `assets/vectors` directory under class named `Svgs`.

So when you refer to `Images` class, auto-complete suggests raster
images only and you know that you can use them with `AssetImage` and
other one with vector rendering library.
So when you refer to `Images` class, auto-complete suggests raster images only and you know that you can use them with `AssetImage` and other one with vector rendering library.

## Multi-path configuration

From Spider `v0.4.0`, multiple paths can be specified for a single group
to collect references from multiple directories and generate all the
references under single dart class.
From Spider `v0.4.0`, multiple paths can be specified for a single group to collect references from multiple directories and generate all the references under single dart class.

#### Example
```yaml
Expand All @@ -219,30 +210,20 @@ groups:
types: [ .png, .jpg, .jpeg, .webp, .webm, .bmp ]
```

By using `paths`, multiple source directories can be specified. Above
example will generate references from `assets/images` and
`assets/more_images/` under a single dart class named `Images`.
By using `paths`, multiple source directories can be specified. Above example will generate references from `assets/images` and `assets/more_images/` under a single dart class named `Images`.

## Generating Tests

Spider `v0.4.0` adds support for generating test cases for generated
dart references to make sure that the asset file is present in the
project. These tests can also be run on CI servers. To enable tests
generation, specify `generate_tests` flag in `spider.yaml` or
`spider.json` configuration file as shown below.
Spider `v0.4.0` adds support for generating test cases for generated dart references to make sure that the asset file is present in the project. These tests can also be run on CI servers. To enable tests generation, specify `generate_tests` flag in `spider.yaml` or `spider.json` configuration file as shown below.

```yaml
generate_tests: true
```
This flag will indicate spider to generate tests for all the generated
dart references.
This flag will indicate spider to generate tests for all the generated dart references.

## Enable Verbose Logging

Spider prefers not to overwhelm terminal with verbose logs that are
redundant for most of the cases. However those verbose logs come quite
handy when it comes to debug anything. You can enable verbose logging by
using `--verbose` option on build command.
Spider prefers not to overwhelm terminal with verbose logs that are redundant for most of the cases. However those verbose logs come quite handy when it comes to debug anything. You can enable verbose logging by using `--verbose` option on build command.

```shell
spider build --verbose
Expand All @@ -251,7 +232,20 @@ spider build --verbose
spider build --watch --verbose
```



#### Liked spider?

Show some love and support by starring the repository.

Or You can

<a href="https://www.buymeacoffee.com/birjuvachhani" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-blue.png" alt="Buy Me A Coffee" style="height: 51px !important;width: 217px !important;" ></a>



## License

```
Copyright © 2020 Birju Vachhani

Expand Down

0 comments on commit d73ad5f

Please sign in to comment.