3. Packages
Local Packages
As we have already explained, this is the place where you will add code and functionality to your sites.
When you do a
npx frontity create, we install three packages for you:@frontity/tiny-routeras an external package. It ends up in thenode_modulesfolder.@frontity/wp-sourceas an external package. It ends up in thenode_modulesfolder.@frontity/mars-themeas a local package. It ends up in thepackagesfolder.
We do this because the most likely situation is that you want to modify the theme, but you don't want to modify the router or source packages.
Once we move a package from
node_modules to packages it becomes a local package and you can change it at will. If you use git, its code is also included in your project and you can commit any change. If you want to use that package in other projects or you want to contribute to the community, you can publish it to npm using npm publish.Be aware, you should not change anything inside
node_modules because that folder is not committed to git and it is thrown away each time you move, reinstall or deploy your project.Finally, it's worth noting that Frontity doesn't know which packages are local and which are external. The only difference between them is the way they are installed in the
package.json. When they are local, they are referenced by folder and when they are external, by the version number:package.json
1
"dependencies": {
2
"frontity": "^0.2.11", // installed in node_modules
3
"@frontity/core": "^0.3.7", // installed in node_modules
4
"@frontity/wp-source": "^0.1.7", // installed in node_modules
5
"@frontity/tiny-router": "^0.3.4", // installed in node_modules
6
"@frontity/mars-theme": "./packages/mars-theme" // installed in packages
7
}
Copied!
If you want to install a new Frontity package you can follow this guide: Install a new Frontity package.
Package Folder Structure
Packages have their own
package.json file. Its code is inside the /src folder.1
my-frontity-project/
2
|__ ...
3
|__ packages/
4
|__ my-theme/
5
|__ package.json
6
|__ src/
7
|__index.js
Copied!
Let's review this in detail.
Package.json
The
package.json file is where you can write the info (name, description, author, repository, version...) of the package. It's just a regular package.json file, so nothing fancy here.It also lists the npm
dependencies for the package. The "dependencies" field gets automatically populated when you run npm install some-npm-package in the package folder.1
cd packages/my-awesome-theme
2
npm install some-npm-package
Copied!
/packages/my-awesome-theme/package.json
1
{
2
"name": "my-awesome-theme",
3
"description": "An awesome theme for Frontity",
4
...
5
"dependencies": {
6
"some-npm-package": "^2.2.6"
7
}
8
}
Copied!
Packages need their own
package.json file because:- Frontity treats them like any other npm package found in
node_modules. - They can be published to npm independently 🚀
- They have their own name, version, authors and license.
Entry Points
By default only one file is needed:
/src/index.js.In some cases you may want to use different code in your client than in your server. Then you can use two files,
/src/client.js and /src/server.js.Publishing Local Packages
One thing we wanted to make sure in Frontity is that publishing packages was really easy.
For that reason, Frontity packages don't need to be transpiled. They can be written in either JavaScript or TypeScript. So, look ma, no build step!
They can be published to npm directly from the
/packages folder of your Frontity project:1
cd packages/my-awesome-theme
2
npm publish
Copied!
Now
my-theme is available in npm! Any other Frontity user can install it using:1
npm install my-awesome-theme
Copied!
And then including it in their
frontity.settings.js file:1
{
2
name: "my-site",
3
packages: [
4
"@frontity/my-awesome-theme",
5
"@frontity/tiny-router",
6
"@frontity/wp-source"
7
]
8
}
Copied!
Yes, it is that simple :)
Package exports
Packages can export any of these elements in their
index.js file:- Roots: React components that will be included in the app.
- Fills: React components that will be included in the app, but injected after the roots.
- State: A JavaScript object containing all the state exposed by your package.
- Actions: A set of actions that your package needs to work or expose for other packages.
- Libraries: Any additional tools that your package exposes for other packages.
For example, a simple theme could be like this:
/packages/my-awesome-theme/src/index.js
1
import Theme from "./components";
2
3
export default {
4
roots: {
5
theme: Theme // <- This is the root component of your theme.
6
},
7
state: {
8
theme: {
9
menu: [
10
["Home", "/"],
11
["About", "/about"]
12
],
13
isMenuOpen: false,
14
featuredImage: {
15
showOnList: true,
16
showOnPost: false
17
}
18
}
19
},
20
actions: {
21
theme: {
22
openMenu: ({ state }) => {
23
state.theme.isMenuOpen = true;
24
},
25
closeMenu: ({ state }) => {
26
state.theme.isMenuOpen = false;
27
}
28
}
29
}
30
}
Copied!
By the way, it's probably good to point out here that in Frontity all packages are equal. Frontity doesn't know which one represents a
theme or which one represents a source. It treats all of them equally.Let's explore the Roots and Fills in the next section.
If you still have any questions about Packages in Frontity, please check out the community forum, which is packed full of answers and solutions to all sorts of Frontity questions. If you don't find what you're looking for, feel free to start a new post.
Last modified 11mo ago