Built by

RSC-Labs

Category

Other

Version

0.8.1

Last updated

May 18, 2024, 17:51:16 PM10 days ago

Medusa documents

What is it?

Medusa documents is a plugin which provides you ability to generate various documents in PDF format. For supported documents, go to Supported documents

How to install?

  1. Install the package with
    Copy to clipboard
    yarn add @rsc-labs/medusa-documents
    or
    Copy to clipboard
    npm i @rsc-labs/medusa-documents
    .
  2. In
    Copy to clipboard
    medusa-config.js
    , add the plugin to the
    Copy to clipboard
    plugins
    array and set
    Copy to clipboard
    enableUI
const plugins = [
// ... other plugins
{
resolve: `@rsc-labs/medusa-documents`,
options: {
enableUI: true
}
}
]
  1. Run migrations, e.g.
    Copy to clipboard
    npx medusa migrations run
    (see: https://docs.medusajs.com/development/entities/migrations/overview) as plugin uses new tables.

INFO: This plugin is still under heavy development so please also remember to run migrations after every update!

Getting started

After installation of a plugin, you will see new option on the sidebar named
Copy to clipboard
Documents
. This will lead you to such view:
NOTE: This README describes
Copy to clipboard
Invoice
as an example of document.
This is a view of your orders. You can notice that it is very similar to
Copy to clipboard
Orders
view. The important difference is in the last column, when you can see
Copy to clipboard
Actions
.
Copy to clipboard
Actions
can handle different documents.
Before you can generate
Copy to clipboard
Invoice
you need to be familiar with two things -
Copy to clipboard
Templates
and
Copy to clipboard
Settings
. Let's go firstly to
Copy to clipboard
Settings
.

Settings

This tab contains settings which are used to generate documents. The most important setting which needs to be set is address. Address reflects information about your company or store, which will be inserted in documents. Go to
Copy to clipboard
Change adddress
to set it.
Depends on the used template, you may want to change a logo or adjust invoice number. Let's just jump now to
Copy to clipboard
Templates
.

Templates

This tab contains supported templates which are used to generate documents. You may see there very basic templates which will be extended in the future. If you set your
Copy to clipboard
Address
correctly and you have at least one
Copy to clipboard
Order
, you may see a preview how invoice will look like.
Note: In preview mode, invoice number is set to 1. Note: If you have picture of template which you would like to have supported, please raise [issue](https://github.com/RSC-Labs/medusa-documents/issues).

Supported documents

NameStatus
Invoice
Packing slip

Generating invoice

If you have your
Copy to clipboard
Template
chosen and
Copy to clipboard
Address
set, then you are able to generate invoice. Go to
Copy to clipboard
Orders
, click on
Copy to clipboard
...
and choose
Copy to clipboard
Generate invoice
. You will see new card opened with your invoice.
Note: We do not store documents, see what it means
After invoice generation, you will see assigned number in the column
Copy to clipboard
Last generated invoice
. This is useful, if you want to download your invoice again or decide to generate new one.

View invoice

If you forgot download your invoice, you may click on
Copy to clipboard
View invoice
to regenerate invoice with the same invoice number.

Invoice number

By default, invoice number is generated based on the last assigned invoice number. In other words - plugin takes the last generated invoice and takes its number to increment it.
We know that your businesss may require different numbering. In such case - go to
Copy to clipboard
Settings
tab and click
Copy to clipboard
Change settings
in
Copy to clipboard
Invoice
. You will see that you can change how your invoice number will look like. For instance, you can make something like
Copy to clipboard
ABC123{invoice_number}
. If your last invoice has base number
Copy to clipboard
10
, then you will get
Copy to clipboard
ABC12311
as your next invoice number.
Sometimes you may want to set your next invoice number (for instance when you have many different clients). You can do it by setting
Copy to clipboard
Forced number
in
Copy to clipboard
Settings
. Please remember that this setting will be applied for newly generated invoice and the incrementation will start over from this new number.
Protip: After setting change, you can always go to `Templates` to see a preview with your next invoice number.

Translation

With version 0.8.0 we introduced translations for documents. You can now configure language for generated documents.
NOTE: We do not support (yet) translations of frontend.
You can configure language of documents using
Copy to clipboard
medusa-config.js
file. Here is the example of Polish language:
const plugins = [
// ... other plugins
{
resolve: `@rsc-labs/medusa-documents`,
options: {
enableUI: true,
documentLanguage: 'pl'
}
}
]

How to add my own translations?

You have two options:
  • create
    Copy to clipboard
    translation.json
    under
    Copy to clipboard
    /assets/i18n/locales/{your-language}
    and create a pull requests - we will be more than happy to merge it
  • create
    Copy to clipboard
    translation.json
    only for local purposes. Then you need to go to
    Copy to clipboard
    node_modules/@rsc-labs/medusa-documents/assets/i18n/locales/{your-language}
    and paste there your translation file.
Please remember that
Copy to clipboard
documentLanguage
in
Copy to clipboard
medusa-config.js
needs to be equal to
Copy to clipboard
{your-language}
.

Q&A

What means "We do not store documents"?

It is simple - every time when you click
Copy to clipboard
Generate invoice
we are taking an
Copy to clipboard
Order
and based on that we generate invoice. The same happens with
Copy to clipboard
View invoice
. It means that if you click generate invoice and your
Copy to clipboard
Order
will change (e.g. line items changed, customer address changed etc.), then
Copy to clipboard
View invoice
will show you the last state of your
Copy to clipboard
Order
. We do not remember Order's state.
However, we remember such things like: invoice number, address or logo, so everything which you set in
Copy to clipboard
Settings
.
Anyway, we encourage you to save your invoice when you generate.

I clicked generate invoice, invoice number has been assigned, but I want to go back to previous number

Now you can do it! Just got to
Copy to clipboard
Settings
tab and click
Copy to clipboard
Change settings
in
Copy to clipboard
Invoice
. Use
Copy to clipboard
Forced number
field to put your next invoice number.

Provided templates are not enough for me, I want more of them, I want customization, I want hide some information etc.

We also see here endless possibilities.. :) Unfortunately, this is a very basic version, but for sure in the future there will be more functionalities.

Proposals, bugs, improvements

If you have an idea, what could be the next highest priority functionality, do not hesistate raise issue here: Github issues

License

MIT

Build your own plugins

Develop your own plugins with our API to speed up your processes.

Make your plugin available via npm for it to be shared in our Plugin Library with the broader Medusa community.