I just gave a few tips I realized were probably not really written anywhere, so I'll put them here.
There are many places in an extension that use namespaced code, variables or structures. It might be a bit complicated to know which one must match each other. Looking at the source code of an existing extension might not help realize the following points, because the same name are usually reused.
Usually you try to use the same naming everywhere to reduce confusion, but as you will see below it's not required, and sometimes not possible to use the same naming.
So here are the main namespaced items:
Not specific to JS or PHP
Package name
The package name is the one you put in composer.json and register on Packagist when you publish your extension.
By convention you should name your package vendor/package, vendor/flarum-ext-package or vendor/flarum-package.
Extension name
The extension name is the unique internal name of your extension inside Flarum. Its value is derived from the package name. It's the package name with flarum- and flarum-ext- removed and / replaced with -.
Example: the package flarum/flarum-ext-tags on Packagist has the internal name flarum-tags. The package flagrow/linguist has the internal name flagrow-linguist.
The package name should be used for translation keys and settings keys. For example the extension flagrow-telegram will use the key flagrow-telegram.admin.settings.title for a translation and flagrow-telegram.botToken for a setting. This is not a strict requirement, for example most Flagrow extensions use vendor.package.setting syntax for their settings.
The extension name is the one saved in the list of enabled extension that Flarum keeps in the database. It's also the name you have to use when registering a setting modal (app.extensionSettings[]) or adding an initializer (app.initializers.add()) via javascript.
It's also a good idea to use the extension name to prefix the database tables and new models/serializers you create. For example Flagrow Linguist uses flagrow-linguist-string as the serializer name for its "strings"
PHP namespace
The PHP namespace is usually in the form Vendor\Package. It does not have to match the package or extension name but it's a good idea to do so. It is registered in the composer.json file and used as the namespace of every file and class that's in your extension.
For example the extension flagrow-linguist uses the Flagrow\Linguist namespace for PHP code.
JS namespace
An extension usually has up to two javascript "packages", called forum (front-end) and admin (admin panel). An additional lib folder holds files common to both packages.
Each of these packages has a Gulpfile.js that defines the namespace for all the code that is in them. The convention is to use the same namespace for both the forum and admin package, as both won't ever be loaded at the same time.
You can use the extension name as the javascript namespace. Another common choice is to name it vendor/package. For example the flagrow-linguist extension uses the JS namespace flagrow/linguist.
The JS namespace is used everytime you import one of your classes via javascript. It's also the one you have to use when registering the bootstrapper for your extension. For example $app->addBootstrapper('flagrow/linguist/main'); will call the function from the file main.js registered under the JS namespace flagrow/linguist.
I've probably forgot stuff but here we go, I hope this is useful to new developers ?
