Skip to content

Commit 2d7f45a

Browse files
lcharettelcharette
authored
Merge pull request #129 from StrykeSlammerII/patch-2
Fleshed out Community Sprinkles
2 parents 19f9c25 + 7367859 commit 2d7f45a

File tree

1 file changed

+107
-5
lines changed
  • pages/06.sprinkles/05.community

1 file changed

+107
-5
lines changed

‎pages/06.sprinkles/05.community/docs.md

+107-5
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,117 @@ taxonomy:
99
One great thing about the **Sprinkle system** is its ability to wrap complete functionality inside a single package. This makes it a great tool to write your website isolated from the core UserFrosting code. It also means it's super easy to share sprinkles between projects... and with other members of the UserFrosting community! That's what we call a **community sprinkle**.
1010

1111
## Finding sprinkles
12-
1312
The best place to look for community sprinkles is on [GitHub](https://github.com). We recommend tagging your community sprinkles with the `userfrosting-sprinkle` topic. This will make it easier for people to find your **community sprinkle** [using GitHub search bar](https://github.com/search?q=topic%3Auserfrosting-sprinkle&type=Repositories).
1413

14+
## Loading a community sprinkle
15+
### Sprinkle recipe
16+
Once you've found a sprinkle you'd like to use in your own project, the first step is to `require` it in [your `composer.json`](/sprinkles/customize#composer-json), along with the core UserFrosting sprinkles.
17+
```json
18+
"require": {
19+
...
20+
"userfrosting/theme-adminlte": "^5.0",
21+
"owlfancy/owlery-sprinkle": "^0.1"
22+
},
23+
```
24+
25+
Next, add *their* recipe to *your* recipe, in the `getSprinkles()` method.
26+
```php
27+
use Owlfancy\Sprinkle\Owlery ; //don't forget to include the sprinkle's namespace!
28+
...
29+
public function getSprinkles(): array
30+
{
31+
return [
32+
Core::class,
33+
Account::class,
34+
Admin::class,
35+
AdminLTE::class, // include any base sprinkles you might need
36+
Owlery::class, // add the community sprinkle as well!
37+
];
38+
}
39+
```
40+
41+
[notice]If the sprinkle does not include Javascript, you're done setting up--skip to the "Installing" section.[/notice]
42+
43+
### Javascript
44+
If the sprinkle includes Javascript, you will need to add it to both the "dependencies" [in your `package.json`](/asset-management/webpack-encore#npm-and-packages-json)...
45+
```json
46+
"dependencies": {
47+
"@userfrosting/sprinkle-admin": "^5.0",
48+
"@userfrosting/theme-adminlte": "^5.0",
49+
"sprinkle-owlery":"github:owlfancy/sprinkle-owlery"
50+
},
51+
```
52+
...*and* to the "sprinkles" [in `/webpack.config.js`](/asset-management/webpack-encore#webpack-encore-configuration).
53+
```js
54+
// List dependent sprinkles and local entries files
55+
const sprinkles = {
56+
AdminLTE: require('@userfrosting/theme-adminlte/webpack.entries'),
57+
Admin: require('@userfrosting/sprinkle-admin/webpack.entries'), // core sprinkles come included
58+
Owlery: require('sprinkle-owlery/webpack.entries'),// add any community sprinkles as well
59+
}
60+
```
61+
(We'll talk more about these files in the [Assets chapter](/asset-management)).
62+
63+
[notice=tip]In the `package.json` example above, we're loading the Userfrosting core sprinkles from npm, and the Owlery sprinkle from Github. Each community sprinkle decides where it is published, and should include this in their README.[/notice]
64+
65+
## Installing a community sprinkle
66+
Once you've added the sprinkle to the recipe, `composer.json`, and (if needed) `package.json`, you're ready to use Composer and [Bakery](/cli/commands#bake) to download and install the files.
67+
```
68+
composer update
69+
php bakery bake
70+
```
71+
72+
### Database (optional)
73+
If needed, [migrations](/cli/commands#migrate) and [seeds](/cli/commands#seed) can be run manually through Bakery.
74+
```txt
75+
php bakery migrate
76+
php bakery seed
77+
```
78+
You can also use `php bakery migrate:status` and `php bakery seed:list` to check what migrations and seeds the sprinkle has added, and if any migrations have not yet been run.
79+
80+
[notice=tip]`php bakery bake` should run migrations automatically, but you can use the above commands later if you don't want to run a full `bake`.[/notice]
81+
82+
[notice=info]Migrations set up the database, if the sprinkle adds features there. Depending on the individual sprinkle, seeds may be convenient management tools and not used during install.[/notice]
83+
1584
## Distributing your sprinkle
1685

17-
If you want to distribute your sprinkle, there are no real requirements that need to be met. You should at least make sure your sprinkle contains a valid `composer.json` file. This file is required to add any sort of class and PSR-4 definition to your sprinkle, so you already have one. Make sure it contains up-to-date information; your name and license details are always welcome. If you include a `type` key, be sure it's defined as `userfrosting-sprinkle` in your sprinkles `composer.json` file--but this is not required as of UserFrosting 5.
86+
### Basic prep work
87+
When you're ready to distribute your sprinkle, first use `composer update` to make sure it is up to date with the latest version of UserFrosting.
88+
89+
Providing documentation and examples in a `README` file will encourage other devs to use your sprinkle. You should specify whether they need to add your sprinkle to `package.json`, if there are any seeds to run, and any other steps needed to fully set up.
90+
[notice=tip]As an example, if your sprinkle adds a new permission, anyone installing your sprinkle may need to manually add that permission to the appropriate roles through the UserFrosting UI.[/notice]
91+
92+
Every sprinkle needs a valid `composer.json` file. This file is required to add any sort of class and PSR-4 definition to your sprinkle, so you already have one. Make sure it contains up-to-date information; your name and license details are always welcome. If you include a `type` key, be sure it's defined as `userfrosting-sprinkle` in your sprinkles `composer.json` file--but this is not required as of UserFrosting 5.
93+
94+
We highly recommend publishing your community sprinkle on GitHub and adding it to [Packagist](https://packagist.org). This lets others include your sprinkle in `composer.json`, similar to how the default sprinkles are already defined.
95+
96+
You may also have some extra steps depending on what features your sprinkle provides:
97+
98+
### Database?
99+
If your sprinkle changes the database structure, make sure you bundle a working [migration](/database/migrations) with your sprinkle.
100+
You might also consider whether any seeds would help manage those changes.
101+
102+
### Javascript?
103+
If your sprinkle includes any Javascript, you'll need to show npm how to install it to the `/node_modules` folder. This folder is similar to `/vendor` that Composer uses, so you may see projects with folders in both locations.
104+
105+
[You'll need to flesh out your `package.json`](https://docs.npmjs.com/cli/configuring-npm/package-json) to do this.
106+
```json
107+
"name": "sprinkle-owlery",
108+
"homepage": "https://github.com/owlfancy/sprinkle-owlery",
109+
"license": "BSD-3-Clause",
110+
"repository": "@owlfancy/sprinkle-owlery",
111+
```
112+
113+
[notice=tip]Consider including a ["files" section](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#files), so that only Javascript files are included in `/node_modules`--npm doesn't typically need PHP or Twig files! Different sprinkles may need npm to be aware of different files or folders.[notice]
18114

19-
You should also make sure your sprinkle is up to date with the latest version of UserFrosting. Providing documentation and examples in a `README` file will encourage devs to use your sprinkle. If your sprinkle is interacting with the database, make sure you bundle a working [migration](/database/migrations) with your sprinkle. That's pretty much it!
115+
#### Npmjs
116+
[Npmjs](https://www.npmjs.com/about) is a registry of JS projects, similar to Packagist for Composer.
20117

21-
When sharing a community sprinkle, we highly recommend publishing it on GitHub and adding it to [Packagist](https://packagist.org). This means your sprinkle will now be able to be included in others' `composer.json`, similar to how the default sprinkles are already defined.
118+
When publishing on npm, you also need a ["version" tag](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#version) in your `package.json`. This must follow [Semantic Versioning](https://semver.org/).
22119

23-
When someone installs your sprinkle as a dependency, the last step is to add *your* recipe to *their* Recipe, in the `getSprinkles()` method.
120+
#### Github
121+
If the Javascript is tightly bound to your sprinkle and you've already published your sprinkle on Github, you may decide not to register it with npm. It is possible for npm to pull your code from Github instead. You'll specify this in your `package.json`:
122+
```json
123+
"repository": "github:owlfancy/sprinkle-owlery",
124+
```
125+
[notice=warning]Publishing via Github may [prevent your users from automatically getting updates](https://medium.com/@jonchurch/use-github-branch-as-dependency-in-package-json-5eb609c81f1a) through npm.[/notice]

0 commit comments

Comments
 (0)