Improve documentation for using "demo-" projects with the emulator

[emesterhazy]

Edit

See the first comment I left below. I found a bug in the Dart SDK, so I don't think there's actually an issue in the emulator. That said, I think the docs can definitely be improved. Take a look at the comment for details.

Original Copy

All of the emulator documentation pages mention that the emulator supports demo projects, which are projects prefixed with "demo-". This type of project is recommended since the application will not attempt to connect to production services that are not running in the emulator.

The problem is that there appears to be no other documentation explaining how to use demo projects with the emulator, and they don't seem to work out of the box. There are several other issues mentioning trouble using demo projects with the emulator:

• Firestore data in emulator not showing up in emulator UI #2365
• No collection/docs visible in firestore emulator, but data exists firebase-tools-ui#482
• demo projects can not be initialized without configuration data from real projects #5218
• use Emulator with Firestore without credentials googleapis/java-firestore#361

There are a few problems:

1. There are no clear instructions about how to use a demo project with the emulator. It seems that launching the project with an explicit project name (i.e. firebase emulators:start --project demo-app) is required since firebase use does not provide a way to set a demo project.
2. When I launch the emulator with firebase emulators:start --project demo-app, I can't see any data in the emulator's Firestore web ui. The app is able to connect to it though because updates are posted to the "requests" tab, and the data is persisted across app restarts even with persistence disabled in the SDK.
3. For Flutter at least, it's unclear how the application should be configured and what the effect of the configuration is. There's a demoProjectId argument to Firebase.initializeApp(), but the app is able to connect to the emulator regardless of whether that's specified.

Action Items

1. Please reopen Firestore data in emulator not showing up in emulator UI #2365. It seems to be a real bug, or at least a usage issue that could use a better explanation somewhere.
2. Please add documentation explaining how to use demo projects with the emulator. The current docs say that using a demo project is recommended, but there's no explanation of how to do it and I haven't been able to figure it out after several hours of trying. Is it just a matter of configuring the application to use a demo- prefixed project id? Do we need to configure anything for the emulator itself?

EDIT: It looks like firebase/codelab-friendlychat-android#173 configures a demo project id in one of the Firebase codelabs. In that codelab, the emulator is also launched with the demo project id.

So I think the main questions are:

1. Why is the application able to connect using demo-app as the project id if the emulator is launched with a different project id?
2. Why isn't any data visible in the Firestore web UI when demo-app is used as the project id (Firestore data in emulator not showing up in emulator UI #2365).

@samtstern I think you updated the codelab. Do you have any advice?

Standard Info

Environment info

firebase --version 14.12.1

firebase-tools: emulator

Platform: flutter

Test case

1. Create a flutter project
2. flutterfire configure
3. In your flutter code, initialize Firebase with await Firebase.initializeApp(demoProjectId: 'demo-project');
4. Launch the emulator with firebase emulators:start --project demo-project
5. The app will be able to communicate with the emulator, but none of the datat will appear in the emulator's Firestore web ui.

Steps to reproduce

The steps are listed in the test case.

Expected behavior

The data should be visible in the emulator web ui.

Actual behavior

No data is listed in the emulator web ui.

[emesterhazy]

After more debugging I've found that this is not actually an emulator issue.

There's a bug in the firebase_core Dart SDK that makes configuring a demo project from Dart fail if the demoProjectId argument is used to configure the demo project. I discovered this after launching the emulator with the --debug flag, after which it complained about multiple projects being used. So the reason the emulator UI didn't show any data in Firestore is because the app used a different project id than the one used to launch the emulator.

I've opened a pull request to fix the Dart SDK bug:

• fix: a bug with the demoProjectId arg to Firebase.initializeApp() flutterfire#17703

All that said, I think the Firebase and emulator documentation could be more explicit. A few questions come to mind as a user:

• Is the "demo-" prefix for demo projects just a convention, or is it a "magic" signal to the Firebase SDKs and Emulator that the app is running in a development mode?
• What does the Firebase SDK do differently when a demo project is used?
• What does the Emulator suite do differently when a demo project is used?
• How do I configure my application to use a demo project for development? What values do I need to set for the API key? For the app id? etc...
• How do I launch the emulator to use a demo project?

As far as I can tell, the "demo" project concept was added after this codelab pull request and exists only as a convention. There's nothing special about it other than the fact that the emulator prints a warning that production services will not be used if the project id begins with "demo-". The only reason production resources aren't used is because the project id and options used for "demo" projects are bogus.

If using a demo project for development is a best practice (seems reasonable to me), then it would be great to have a more detailed docs page explaining how to configure the SDK and Emulator correctly. Maybe it is clear to everyone else since I couldn't find much discussion about this online, but it certainly took me a while to sort everything out (the Dart SDK bug didn't help either).

[nomasprime]

Similar issue with Kotin.