Including assets in a Flutter package

Dec 1, 2019 · 8 min read

A guide for package developers

Photo by Bench Accounting on Unsplash

If you are coming to this page wanting to know how to include images, fonts, or other assets in your Flutter app, then you might be in the wrong place. Check out one of these other articles for help:

The guide below is for package developers who need to include assets in their package.

Where to put the assets

So you have an image or font or something that you want to make available to the app developers who use your package. Where do you put it?

One choice is to put it in the lib/ folder.

Who knew that you could put something besides .dart files in the lib/ folder!

Anything in the lib/ folder will get automatically bundled with the app. Those assets will be available to anyone who uses your package. As the package developer, you don’t even need to declare those assets in pubspec.yaml if you are not using them yourself. They’ll still be bundled with the package.

The other choice is to create a new folder in the main project. Call it assets or fonts or whatever you want.

Assets in the main project folder

Any assets that are not in the lib/ folder, though, will not get added to the package’s assets bundle unless you specifically include them in pubspec.yaml:

It is easiest to understand how this works by looking at some examples. I’ll show you four different Flutter packages on that each do it a little bit differently. You’ll see how the assets are handled from both the package author’s perspective and from the package user’s perspective.

Example 1: shrine_images

The shrine_images package isn’t really useful for anything other than providing the image assets for the Shrine app that is part of the Flutter Gallery demo app. But it is helpful for showing how to include assets in a Flutter package, and that was probably the main purpose.

How the package developer did it

The package developer put all of the assets in the lib/ folder like this:

Three different density versions of each image exists. There is nothing else in the lib/ folder except these images. If you look at the pubspec.yaml file, there is no mention at all of any assets. Just including them in the lib/ folder was enough.

How an app developer uses the package

It’s a little hard to follow how the Shrine app uses the package (but see here, here, and here if you are interested), so I’ll make a simple app that uses the shrine_images package.

My app’s pubspec.yaml file looks like this:

Notice two things:

  1. I included as a dependency.
  2. I included under the flutter assets. You start with . Then you give the package name ( in this case). Then you give the location and file name in the lib/ folder. You don’t include itself because that is assumed. I am only using one image in my simple app. If I were using more images I would have to list them all individually (like the Shrine app does). You can’t just specify the folder like you can with local assets.

My main.dart file looks like this:

Note that there is no need to import the shrine_images package at the top of the file.

To get the image you use and provide it the asset name and package name. Here that part is again.

Running the app now gives the following:

an app using the shrine_images package

Example 2: font_awesome_flutter

The font_awesome_flutter package provides a set of fonts with lots of useful icons. The fonts themselves are bundled in the package.

How the package developer did it

The package developer put the font assets in a subfolder of lib/ like this:

However, since the developer is using the assets in the package logic, they also declare the fonts as assets in the pubspec.yaml file:

And here is a snippet of it being used in the icon_data.dart code:

Doing this makes it a lot easier on the package users as you will see.

How an app developer uses the package

An app developer only needs to include font_awesome_flutter as a dependency in the app’s pubspec.yaml file.

There is no need to declare any font assets. The app developer doesn’t even need to know the name of the font files.

You can just import the package and use it directly. Here is main.dart for a simple demo:

You only have to pass the icon data into an Icon widget. This makes it super easy for the app developer.

Running the app now gives

an app using the font_awesome_flutter package

Example 3: crypto_font_icons

The crypto_font_icons package is similar to font_awesome_flutter in that it provides a custom font for app developers to use. The reason I mention it is that the package developer used a different folder structure.

How the package developer did it

Rather than putting the font in the lib/ folder, the package developer made a fonts folder in the main package folder like this:

Then pubspec.yaml looks like this:

By listing the font as an asset in pubspec.yaml, it still gets included in the assets bundle, and thus will be available to app developers who use the package.

Everything else on the package developer’s side is basically the same as the font_awesome_flutter package.

How an app developer uses the package

From the perspective of the app developer, it doesn’t matter at that the package developer didn’t put the assets in the lib/ folder. That’s all hidden away by the package.

Just depend on it

And use it like we did in the font_awesome_flutter example above.

This gives

an app using the crypto_font_icons package

Example 4: mongol

In my original version of this article I only had three examples. Presenting these examples to you was my way of learning how to do it myself. However, I discovered while working on my own package that the examples above did not cover how to provide a font itself. Example 1 used an widget to specify the package and examples 2 and 3 used an widget to specify the package. But I wanted to share an entire font.

My package is called mongol. You aren’t likely to ever use it unless you are one of the few Flutter devs creating apps for vertical Mongolian text. However, since the source code is on GitHub, you can see how I was able to provide a font file (not just icon data) to the package users.

How the package developer did it

I included the Mongolian font file in the lib folder like this:

Since it is in the lib/ folder it will be automatically included in the package bundle. But since I was using it in the package code to make it the default font for the widget, I also declared it in pubspec.yaml:

The name is descriptive but arbitrary. I could have called the font family if I’d wanted to.

The trick next was how to provide access to that font. Using isn’t enough because that doesn’t include the package info. The key was to use the following string pattern when the font family was needed:

For my package this translated to

In the package code I made a class for this:

How an app developer uses the package

Since the package uses the string internally, the package user doesn’t need to know it at all.

Doing something like this works fine:



Running that gives

an app using the mongol package

However, if the app user wanted to use the font file directly they could use the string to access it. For example, replace the widget with a standard widget:

which gives

using the font directly from the package asset bundle

For help accessing other file types, see this Stack Overflow Q&A.


Its great that the Pub packages are open source so that we can learn by seeing how other people have solved the same problems. If there are ways that you think the current process of adding assets to a package can be improved, first check out this GitHub issue. And if there are any improvements or insights that you can add to this guide, please leave a comment below.

Flutter Community

Articles and Stories from the Flutter Community


Written by


A Flutter and Dart developer with a background in Android and iOS. Follow me on Twitter @suragch1 for new article notifications.

Flutter Community

Articles and Stories from the Flutter Community

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade