2.0: calling importLibrary immediately after setOptions fails with "google.maps.importLibrary is not installed."

[samuelcole]

reading through the code, it looks like setOptions calls bootstrap which adds a script element to the page, which naturally loads async

so then if you immediately call importLibrary it will fail because window.google.maps is not available yet

it seems like importLibrary needs to know if setOptions has been called and if there is a script loading, so that it can await that script onload event.

[usefulthink]

Do you have an example that reproduces the problem?

EDIT:
Just did exactly what you suggested doesn't work, and it works correctly:
https://codesandbox.io/p/sandbox/clever-varahamihira-hfgdrc?file=%2Fsrc%2Findex.ts

The bootstrapping process isn't quite easy to understand and due to the partly minimized code in bootstrap.js slightly obfuscated.

I think what you were missing is that the bootstrap function defines the initial version of the google.maps.importLibrary function (as is documented in bootstrap.d.ts...):

js-api-loader/src/bootstrap.js

Line 42 in 2ad4e0a

namespace[IMPORT_API_NAME] ? console.warn(PRODUCT_NAME + " only loads once. Ignoring:", bootstrapParams) : namespace[IMPORT_API_NAME] = (libraryName, ...args) => libraries.add(libraryName) && triggerBootstrap().then(() => namespace[IMPORT_API_NAME](libraryName, ...args));

It also doesn't wait for the script to load (since it might load multiple scripts), but instead it waits for the internal callback to be called.

(also, please be sure that there actually is a problem before opening an issue about it)

[samuelcole]

well, i'm sure it's a problem, because it's happening in my app, i'll see if i can make a reduction because this is blocking us from upgrading to 2.0

[samuelcole]

ok! i think i got it:

we were doing:

import { importLibrary, setOptions } from "@googlemaps/js-api-loader";
import getEnvironment from "./getEnvironment";

const { NEXT_PUBLIC_GOOGLE_MAPS_API_KEY } = getEnvironment("public");

setOptions({
  key: NEXT_PUBLIC_GOOGLE_MAPS_API_KEY,
  v: "weekly",
  libraries: ["places", "geocoding"],
});

export { importLibrary };

my understanding was that importing importLibrary from that file would execute the file, but for whatever reason, SWC did not see fit to include the intermediate file, meaning setOptions never ran (btw, i do think the error message can be improved...)

i changed the file to be:

import { importLibrary, setOptions } from "@googlemaps/js-api-loader";
import getEnvironment from "./getEnvironment";

const { NEXT_PUBLIC_GOOGLE_MAPS_API_KEY } = getEnvironment("public");

if (typeof window !== "undefined") {
  setOptions({
    key: NEXT_PUBLIC_GOOGLE_MAPS_API_KEY,
    v: "weekly",
    libraries: ["places", "geocoding"],
  });
}

export default importLibrary;

just as a note, this file is now run isomorphic under next.js, so that's why i had to add the check for window, so it NO-OPs on the server.

and all is right in the world...

[usefulthink]

Apologies, your initial wording suggested you inferred that from just reading the code so I did a quick repro and found nothing wrong...

Your case is actually pretty interesting, what I think is happening is that your bundler doesn't know that there is this "global state" connection between the two functions and it incorrectly assumes that importLibrary is a function free of side effects. If that were the case it would be acceptable to remove the intermediate module since the re-exported function is everything you actually need. By reexporting the function as default, this behaviour might be changed.

Now I'm wondering if it is possible for us to let bundlers know that there are side-effects in those functions?

[usefulthink]

@samuelcole I now published a version 2.0.1 that includes a sideEffects specification in the package.json. It would be cool if you could test that with your initial setup to see if that setting fixes it.

[samuelcole]

@usefulthink good call! it is a side effect, and i was running "sideEffects": false, so it's on my end:

i added:

"sideEffects": [
    "./util/googleMapsLoader.ts"
  ],

to package.json

which allows me to do:

import { importLibrary, setOptions } from "@googlemaps/js-api-loader";
import getEnvironment from "./getEnvironment";

const { NEXT_PUBLIC_GOOGLE_MAPS_API_KEY } = getEnvironment("public");

if (typeof window !== "undefined") {
  setOptions({
    key: NEXT_PUBLIC_GOOGLE_MAPS_API_KEY,
    v: "weekly",
    libraries: ["places", "geocoding"],
  });
}

export { importLibrary };

just a note on the new functional style of @googlemaps/js-api-loader, which i love, but setOptions has a pretty big side effect (it adds a script tag to the document) so it's not purely functional.

i'm not sure how to do it differently, since we're tied to the reality that the google maps api is loaded with script tags, but a couple ideas:

1. importLibrary could take options, and add the script tag if it's not there yet
2. setOptions could return importLibrary, to make it harder to call importLibrary before calling setOptions

i also believe the error message could be improved google.maps.importLibrary is not installed. does not give a hint that it's actually because setOptions wasn't called yet.

[usefulthink]

Yeah, you're right, it's really not at all "functional" as in FP, it's just using functions instead of objects and methods. We should probably adjust the wording in the docs...

Here's a couple of thoughts that went into this design that run against your suggestions:

• we wanted to stick as close to the dynamic library import script that is provided for usage without any bundler, so having an async importLibrary(name) function was a given
• we explicitly wanted a separation between configuring the loader (which happens once, probably during app startup) and importing something from the library (which happens all the time).
• if the importLibrary function were something you have to create somehow, you're also in the situation where you have to pass it around to everywhere its needed, which would become something that hinders the adoption of the new pattern to import everything you need, where you need it, instead of just loading everything upfront and using it via the global namespace.

i also believe the error message could be improved google.maps.importLibrary is not installed. does not give a hint that it's actually because setOptions wasn't called yet.

Hm, there should have been a message logged in development as well, maybe there's something wrong with how we're handling the development-mode:

js-api-loader/src/index.ts

Line 109 in 2e23cd8

logDevWarning(MSG_SET_OPTIONS_NOT_CALLED);