Frontity Docs
  • Β» Welcome to Frontity
  • πŸš€Getting started
    • Quick start guide
  • πŸ“ƒAbout Frontity
    • Frontity features
    • Browser support
    • Get involved
  • πŸ“šCore Concepts
    • 1. Project
    • 2. Settings
    • 3. Packages
    • 4. Roots
    • 5. State
    • 6. Actions
    • 7. Libraries
    • 8. Namespaces
    • 9. Styles
  • πŸ—οΈArchitecture
    • Decoupled Mode
    • Embedded Mode
  • 🌎Deployment
    • Deploy Frontity using Vercel
    • Deploy Frontity on Layer0
    • Deploy Frontity on Heroku
  • πŸŒ—Isomorphic React
  • ⚑️ Perfomance
    • Caching
    • Link prefetching
    • Lazy Loading
    • Code Splitting
  • πŸ”ŽSEO
  • πŸ“–Guides
    • Setting the URL of the WordPress data source
    • Using Environment Variables in a Frontity project
    • WordPress requirements for Frontity
    • URLs in a Migration from WordPress to Frontity Decoupled Mode
    • Frontity Query Options
    • Redirections with Frontity
    • Understanding a Frontity project
    • Add a new Frontity package or theme to your project
    • How to share your Frontity project
    • Understanding Mars Theme
    • Working with processors
    • How to process page-builder content in Frontity
    • Keep Frontity Updated
    • Troubleshooting
    • JavaScript
    • React
  • πŸ‘Contributing
    • How to contribute?
    • Contributing Guide
Powered by GitBook
On this page
  • A Frontity theme project structure
  • The Project
  • The Theme
  • Why this structure?
  • Sharing your GitHub repository on CodeSandbox
  • Example: Frontity Chakra Theme
  • Clone and launch it locally
  • Publish the theme (as npm package)

Was this helpful?

  1. Guides

How to share your Frontity project

PreviousAdd a new Frontity package or theme to your projectNextUnderstanding Mars Theme

Last updated 4 years ago

Was this helpful?

When you create a Frontity project most of the times you'll end up creating a custom theme:

  • Because you need some specific design and features for your project

  • Because you directly want to create a theme that can be reused by others (like or )

Whatever the case is, you may want the community:

  • To be able to check the code of your theme

  • To be able to install it locally so it can be debugged β†’ this will help the community to help you with any issue you may have with your project/theme

  • To be able to install it as an npm package (eventually) so it can be easily reused in some other projects

Here you have a few things to consider to ease contributions and support from the community to your theme

A Frontity theme project structure

In Frontity, themes are packages that can be published in npm so they can be installed and used in any other Frontity project

You can find all the Frontity themes looking for the tag at npm

The suggested structure for developing new themes that works with Frontity is the following one

/my-frontity-project
|__ frontity.settings.js
|__ package.json
|__ /node_modules
|__ /packages
    |__ /awesome-theme
    |__ /my-custom-extension-1
    |__ /my-custom-extension-2

This is the structure we recommend you to upload to your remote git repository (Github, Bitbucket or any other)

Examples:

In this structure, the theme you're developing is a local dependency of the main package.json

"dependencies": {
    "awesome-theme": "file:packages/awesome-theme"
  }

This structure implies having a main Frontity project (root package.json) and some packages (each one with its own package.json) under the packages folder

/my-frontity-project
...
|__ package.json
...
|__ /packages
    |__ /awesome-theme
    |__ /my-custom-extension-1
    |__ /my-custom-extension-2

So, to create a custom theme project we recommend you to:

  1. Create a Frontity project β†’ npx frontity create awesome-theme-project

  2. Create a Frontity package (your theme) β†’ npx frontity create-package awesome-theme

These files in the root represents the Frontity project that can be launched and that will allow to see the theme (or any other package) in action

In the root folder you'll find the following:

frontity.setting.js

For example:

...
"packages": [
    {
      "name": "awesome-theme"
    },
...

node_modules

packages

package.json

This package.json is used when you publish a package in npm, but this Frontity project is not meant to be published

Notice the "private": true preventing this package (the main Frontity project defined in the root) being published

The Theme

With this structure you can develop your theme as a package inside the packages folder.

Each one of these packages will have its own package.json and these packages are the ones meant to be published (npm publish)

Why this structure?

This structure allows to:

  • Launch the project using the theme locally

  • Publish the theme independently

So any developer can clone this project, launch the Frontity project locally, have a look at how the theme looks like & behave and make contributions (pull requests) to your repository (that can be eventually merged into the main repository).

And also, the owner of the theme still can publish those new updates independently (from the theme folder, packages/awesome-theme in this case)

Sharing your GitHub repository on CodeSandbox

GitHub repositories containing Frontity projects with the structure explained above, can be directly opened in CodeSandbox by using one of the following URL structures:

https://githubbox.com/<%GITHUB_ACCOUNT%>/<%FRONTITY_PROJECT_REPOSITORY%>
https://codesandbox.io/s/github/<%GITHUB_ACCOUNT%>/<%FRONTITY_PROJECT_REPOSITORY%>

Example: Frontity Chakra Theme

Clone and launch it locally

/frontity-chakra-ui-theme
|__ frontity.settings.js
|__ package.json
...
|__ /packages
    |__ /frontity-chakra-theme

From the root of the project we can do

npm install

This command will install the dependencies of the Frontity project and the dependencies of its dependencies, just as any other npm package

"dependencies": {
   ...
    "frontity-chakra-theme": "./packages/frontity-chakra-theme"
  }

All needed dependencies (the ones defined for the Frontity project and the ones defined for the theme) are installed

Once we have all the dependencies installed you can do (from the root)

npx frontity dev

This will launch the Frontity project using this theme

Publish the theme (as npm package)

> npm search frontity-chakra-theme
NAME                      | DESCRIPTION          | AUTHOR          | DATE       | VERSION  | KEYWORDS
frontity-chakra-theme     | A frontity theme…    | =segunadebayo   | 2020-01-28 | 0.0.2    | wordpress frontity frontity-theme frontity
cd packages/frontity-chakra-theme
npm publish

Take into account that there cannot be two packages with the same name (property name in your package.json) so if you try to publish a package that is already published you will get an error

This type of dependency is automatically defined if you create the package (theme) w/ the Frontity command npx frontity create-package awesome-theme Β» Read more about

A file containing the settings for your project (among other settings you'll usually define the use of this theme)

A folder, where the dependencies of the project are installed

A folder where your local packages live

And a with the configuration & dependencies for the Frontity project.

In Frontity you can create a new package by doing npx frontity create-package <my package name> (from the root of the Frontity project) Β» Read more about

For example this repo can be opened directly in CodeSandbox with links like:

Let's take as an example of a Frontity theme available:

As ready to be installed and used as a theme in any Frontity project

In a ready to be cloned and launched locallly, and also ready to accept contributions from the community via

Once we we can see the project follows the structure of a typical Frontity project

So, as Frontity Chakra Theme is also one of the dependencies () is:

npm install <folder>

As we can see frontity-chakra-theme is published as

How did published this theme once he finished it? Just by doing:

πŸ“–
@frontity/mars-theme
@frontity/twentytwenty-theme
frontity-theme
https://github.com/chakra-ui/frontity-chakra-ui-theme
https://github.com/imranhsayed/frontity-twentynineteen
https://github.com/alexadark/frontity-starter-theme
https://github.com/igmoweb/igmoweb.com
https://github.com/goiblas/personal-blog
frontity create-package
The Project
frontity.setting.js
/node_modules/
packages
package.json
frontity create-package
https://github.com/frontity-demos/demo-custom-homepage-categories
https://codesandbox.io/s/github/frontity-demos/demo-custom-homepage-categories
https://githubbox.com/frontity-demos/demo-custom-homepage-categories
Frontity Chakra Theme
an npm package
GitHub repository
Pull Requests
clone the theme
a local dependency
Read more about
an npm package
@segunadebayo